kensho-kfinance 3.2.5__tar.gz → 3.2.7__tar.gz

{kensho_kfinance-3.2.5/kensho_kfinance.egg-info → kensho_kfinance-3.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 3.2.5
+Version: 3.2.7
 Summary: Python CLI for kFinance
 Author-email: Luke Brown <luke.brown@kensho.com>, Michelle Keoy <michelle.keoy@kensho.com>, Keith Page <keith.page@kensho.com>, Matthew Rosen <matthew.rosen@kensho.com>, Nick Roshdieh <nick.roshdieh@kensho.com>
 Project-URL: source, https://github.com/kensho-technologies/kfinance

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7/kensho_kfinance.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 3.2.5
+Version: 3.2.7
 Summary: Python CLI for kFinance
 Author-email: Luke Brown <luke.brown@kensho.com>, Michelle Keoy <michelle.keoy@kensho.com>, Keith Page <keith.page@kensho.com>, Matthew Rosen <matthew.rosen@kensho.com>, Nick Roshdieh <nick.roshdieh@kensho.com>
 Project-URL: source, https://github.com/kensho-technologies/kfinance

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+# v3.2.7
+- Fix validator for UnifiedIdTripleResponse
+
+# v3.2.6
+- Return pydantic models from KfinanceTool._run
+
 ## v3.2.5
 - Add requested EV ratio line items
 

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/client/fetch.py

@@ -26,7 +26,10 @@ from kfinance.domains.companies.company_models import (
 from kfinance.domains.competitors.competitor_models import CompetitorResponse, CompetitorSource
 from kfinance.domains.earnings.earning_models import EarningsCallResp
 from kfinance.domains.line_items.line_item_models import LineItemResponse
-from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_models import MergersResp
+from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_models import (
+    MergerInfo,
+    MergersResp,
+)
 from kfinance.domains.prices.price_models import HistoryMetadataResp, PriceHistory
 from kfinance.domains.segments.segment_models import SegmentsResp, SegmentType
 from kfinance.domains.statements.statement_models import StatementsResp
@@ -645,17 +648,16 @@ class KFinanceApiClient:
     def fetch_merger_info(
         self,
         transaction_id: int,
-    ) -> dict:
+    ) -> MergerInfo:
         """Fetches information about the given merger or acquisition, including the timeline, the participants, and the considerations.
 
-        Returns a complex dictionary.
         :param transaction_id: The transaction ID to filter on.
         :type transaction_id: int
         :return: A dictionary containing the timeline, the participants, and the considerations (eith their details) of the transaction.
-        :rtype: dict
+        :rtype: MergerInfo
         """
         url = f"{self.url_base}merger/info/{transaction_id}"
-        return self.fetch(url)
+        return MergerInfo.model_validate(self.fetch(url))
 
     def fetch_advisors_for_company_in_merger(
         self,

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/client/kfinance.py

@@ -31,13 +31,21 @@ from kfinance.client.meta_classes import (
     DelegatedCompanyFunctionsMetaClass,
 )
 from kfinance.client.models.date_and_period_models import (
+    CurrentPeriod,
+    LatestAnnualPeriod,
     LatestPeriods,
+    LatestQuarterlyPeriod,
     Periodicity,
     YearAndQuarter,
 )
 from kfinance.client.server_thread import ServerThread
 from kfinance.domains.companies.company_models import IdentificationTriple
 from kfinance.domains.earnings.earning_models import EarningsCall, TranscriptComponent
+from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_models import (
+    MergerConsideration,
+    MergerInfo,
+    MergerTimelineElement,
+)
 from kfinance.domains.prices.price_models import HistoryMetadataResp, PriceHistory
 
 
@@ -1266,24 +1274,13 @@ class MergerOrAcquisition:
         self.transaction_id = transaction_id
         self.merger_title = merger_title
         self.closed_date = closed_date
-        self._merger_info: dict | None = None
+        self._merger_info: MergerInfo | None = None
 
     @property
-    def merger_info(self) -> dict:
+    def merger_info(self) -> MergerInfo:
         """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)
-            if "timeline" in self._merger_info and self._merger_info["timeline"]:
-                timeline = pd.DataFrame(self._merger_info["timeline"])
-                timeline["date"] = pd.to_datetime(timeline["date"])
-                self._merger_info["timeline"] = timeline
-            if (
-                "consideration" in self._merger_info
-                and self._merger_info["consideration"]
-                and "details" in self._merger_info["consideration"]
-            ):
-                details = pd.DataFrame(self._merger_info["consideration"]["details"])
-                self._merger_info["consideration"]["details"] = details
         return self._merger_info
 
     @property
@@ -1292,9 +1289,9 @@ class MergerOrAcquisition:
         return self.merger_title
 
     @property
-    def get_timeline(self) -> pd.DataFrame:
+    def get_timeline(self) -> list[MergerTimelineElement]:
         """The timeline of the merger includes every new status, along with the dates of each status change."""
-        return self.merger_info["timeline"]
+        return self.merger_info.timeline
 
     @property
     def get_participants(self) -> dict:
@@ -1308,8 +1305,8 @@ class MergerOrAcquisition:
                 transaction_id=self.transaction_id,
                 company=Company(
                     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"],
+                    company_id=self.merger_info.participants.target.company_id,
+                    company_name=self.merger_info.participants.target.company_name,
                 ),
             ),
             "buyers": [
@@ -1318,11 +1315,11 @@ class MergerOrAcquisition:
                     transaction_id=self.transaction_id,
                     company=Company(
                         kfinance_api_client=self.kfinance_api_client,
-                        company_id=company["company_id"],
-                        company_name=company["company_name"],
+                        company_id=company.company_id,
+                        company_name=company.company_name,
                     ),
                 )
-                for company in self.merger_info["participants"]["buyers"]
+                for company in self.merger_info.participants.buyers
             ],
             "sellers": [
                 ParticipantInMerger(
@@ -1330,16 +1327,16 @@ class MergerOrAcquisition:
                     transaction_id=self.transaction_id,
                     company=Company(
                         kfinance_api_client=self.kfinance_api_client,
-                        company_id=company["company_id"],
-                        company_name=company["company_name"],
+                        company_id=company.company_id,
+                        company_name=company.company_name,
                     ),
                 )
-                for company in self.merger_info["participants"]["sellers"]
+                for company in self.merger_info.participants.sellers
             ],
         }
 
     @property
-    def get_consideration(self) -> dict:
+    def get_consideration(self) -> MergerConsideration:
         """A merger's consideration is the assets exchanged for the target company.
 
         Properties in the consideration include:
@@ -1354,7 +1351,7 @@ class MergerOrAcquisition:
                 - The number of shares in the target company.
                 - The current gross total of the consideration detail.
         """
-        return self.merger_info["consideration"]
+        return self.merger_info.consideration
 
 
 @add_methods_of_singular_class_to_iterable_class(Company)
@@ -1903,16 +1900,18 @@ class Client:
         most_recent_year_annual = current_year - 1
 
         current_month = datetime_now.month
-        latest: LatestPeriods = {
-            "annual": {"latest_year": most_recent_year_annual},
-            "quarterly": {"latest_quarter": most_recent_qtr, "latest_year": most_recent_year_qtrly},
-            "now": {
-                "current_year": current_year,
-                "current_quarter": current_qtr,
-                "current_month": current_month,
-                "current_date": datetime_now.date().isoformat(),
-            },
-        }
+        latest = LatestPeriods(
+            annual=LatestAnnualPeriod(latest_year=most_recent_year_annual),
+            quarterly=LatestQuarterlyPeriod(
+                latest_quarter=most_recent_qtr, latest_year=most_recent_year_qtrly
+            ),
+            now=CurrentPeriod(
+                current_year=current_year,
+                current_quarter=current_qtr,
+                current_month=current_month,
+                current_date=datetime_now.date(),
+            ),
+        )
         return latest
 
     @staticmethod
@@ -1932,9 +1931,9 @@ class Client:
         year_n_quarters_ago = total_quarters_completed_n_quarters_ago // 4
         quarter_n_quarters_ago = total_quarters_completed_n_quarters_ago % 4 + 1
 
-        year_quarter_n_quarters_ago: YearAndQuarter = {
-            "year": year_n_quarters_ago,
-            "quarter": quarter_n_quarters_ago,
-        }
+        year_quarter_n_quarters_ago = YearAndQuarter(
+            year=year_n_quarters_ago,
+            quarter=quarter_n_quarters_ago,
+        )
 
         return year_quarter_n_quarters_ago

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/client/models/date_and_period_models.py

@@ -1,5 +1,6 @@
-from typing import TypedDict
+from datetime import date
 
+from pydantic import BaseModel
 from strenum import StrEnum
 
 
@@ -21,28 +22,28 @@ class Periodicity(StrEnum):
     year = "year"
 
 
-class YearAndQuarter(TypedDict):
+class YearAndQuarter(BaseModel):
     year: int
     quarter: int
 
 
-class LatestAnnualPeriod(TypedDict):
+class LatestAnnualPeriod(BaseModel):
     latest_year: int
 
 
-class LatestQuarterlyPeriod(TypedDict):
+class LatestQuarterlyPeriod(BaseModel):
     latest_quarter: int
     latest_year: int
 
 
-class CurrentPeriod(TypedDict):
+class CurrentPeriod(BaseModel):
     current_year: int
     current_quarter: int
     current_month: int
-    current_date: str
+    current_date: date
 
 
-class LatestPeriods(TypedDict):
+class LatestPeriods(BaseModel):
     annual: LatestAnnualPeriod
     quarterly: LatestQuarterlyPeriod
     now: CurrentPeriod

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/client/tests/test_fetch.py

@@ -311,7 +311,9 @@ class TestFetchItem(TestCase):
     def test_fetch_merger_info(self) -> None:
         transaction_id = 554979212
         expected_fetch_url = f"{self.kfinance_api_client.url_base}merger/info/{transaction_id}"
-        self.kfinance_api_client.fetch_merger_info(transaction_id=transaction_id)
+        # Validation error is ok, we only care that the function was called with the correct url
+        with pytest.raises(ValidationError):
+            self.kfinance_api_client.fetch_merger_info(transaction_id=transaction_id)
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
     def test_fetch_advisors_for_company_in_merger(self) -> None:

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/client/tests/test_objects.py

@@ -14,7 +14,6 @@ from kfinance.client.kfinance import (
     BusinessRelationships,
     Company,
     Earnings,
-    MergerOrAcquisition,
     ParticipantInMerger,
     Security,
     Ticker,
@@ -29,7 +28,10 @@ from kfinance.domains.capitalizations.capitalization_models import Capitalizatio
 from kfinance.domains.companies.company_models import CompanyIdAndName, IdentificationTriple
 from kfinance.domains.earnings.earning_models import EarningsCallResp
 from kfinance.domains.line_items.line_item_models import LineItemResponse
-from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_models import MergersResp
+from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_models import (
+    MergerInfo,
+    MergersResp,
+)
 from kfinance.domains.prices.price_models import HistoryMetadataResp
 from kfinance.domains.segments.segment_models import SegmentsResp
 from kfinance.domains.statements.statement_models import StatementsResp
@@ -254,39 +256,41 @@ MOCK_ISIN_DB = {msft_isin: msft_id_triple.model_dump(mode="json")}
 MOCK_CUSIP_DB = {msft_cusip: msft_id_triple.model_dump(mode="json")}
 
 MOCK_MERGERS_DB = {
-    msft_buys_mongo: {
-        "timeline": [
-            {"status": "Announced", "date": "2000-09-12"},
-            {"status": "Closed", "date": "2000-09-12"},
-        ],
-        "participants": {
-            "target": {"company_id": 31696, "company_name": "MongoMusic, Inc."},
-            "buyers": [{"company_id": 21835, "company_name": "Microsoft Corporation"}],
-            "sellers": [
-                {"company_id": 18805, "company_name": "Angel Investors L.P."},
-                {"company_id": 20087, "company_name": "Draper Richards, L.P."},
-                {"company_id": 22103, "company_name": "BRV Partners, LLC"},
-                {"company_id": 23745, "company_name": "Venture Frogs, LLC"},
-                {"company_id": 105902, "company_name": "ARGUS Capital International Limited"},
-                {"company_id": 880300, "company_name": "Sony Music Entertainment, Inc."},
-            ],
-        },
-        "consideration": {
-            "currency_name": "US Dollar",
-            "current_calculated_gross_total_transaction_value": "51609375.000000",
-            "current_calculated_implied_equity_value": "51609375.000000",
-            "current_calculated_implied_enterprise_value": "51609375.000000",
-            "details": [
-                {
-                    "scenario": "Stock Lump Sum",
-                    "subtype": "Common Equity",
-                    "cash_or_cash_equivalent_per_target_share_unit": None,
-                    "number_of_target_shares_sought": "1000000.000000",
-                    "current_calculated_gross_value_of_consideration": "51609375.000000",
-                }
+    msft_buys_mongo: MergerInfo.model_validate(
+        {
+            "timeline": [
+                {"status": "Announced", "date": "2000-09-12"},
+                {"status": "Closed", "date": "2000-09-12"},
             ],
-        },
-    }
+            "participants": {
+                "target": {"company_id": 31696, "company_name": "MongoMusic, Inc."},
+                "buyers": [{"company_id": 21835, "company_name": "Microsoft Corporation"}],
+                "sellers": [
+                    {"company_id": 18805, "company_name": "Angel Investors L.P."},
+                    {"company_id": 20087, "company_name": "Draper Richards, L.P."},
+                    {"company_id": 22103, "company_name": "BRV Partners, LLC"},
+                    {"company_id": 23745, "company_name": "Venture Frogs, LLC"},
+                    {"company_id": 105902, "company_name": "ARGUS Capital International Limited"},
+                    {"company_id": 880300, "company_name": "Sony Music Entertainment, Inc."},
+                ],
+            },
+            "consideration": {
+                "currency_name": "US Dollar",
+                "current_calculated_gross_total_transaction_value": "51609375.000000",
+                "current_calculated_implied_equity_value": "51609375.000000",
+                "current_calculated_implied_enterprise_value": "51609375.000000",
+                "details": [
+                    {
+                        "scenario": "Stock Lump Sum",
+                        "subtype": "Common Equity",
+                        "cash_or_cash_equivalent_per_target_share_unit": None,
+                        "number_of_target_shares_sought": "1000000.000000",
+                        "current_calculated_gross_value_of_consideration": "51609375.000000",
+                    }
+                ],
+            },
+        }
+    )
 }
 
 
@@ -1012,64 +1016,3 @@ class TestCompanyEarnings(TestCase):
         """test company next_earnings property"""
         next_earnings = self.msft_company.next_earnings
         self.assertEqual(next_earnings.key_dev_id, 1916266380)
-
-
-class TestMerger(TestCase):
-    def setUp(self):
-        self.kfinance_api_client = MockKFinanceApiClient()
-        self.merger = MergerOrAcquisition(
-            kfinance_api_client=self.kfinance_api_client,
-            transaction_id=int(msft_buys_mongo),
-            merger_title="Closed M/A of MongoMusic, Inc.",
-            closed_date=date(2021, 1, 1),
-        )
-
-    def test_merger_info(self) -> None:
-        expected_merger_info = MOCK_MERGERS_DB[msft_buys_mongo]
-        merger_info = {
-            "timeline": [
-                {"status": timeline["status"], "date": timeline["date"].strftime("%Y-%m-%d")}
-                for timeline in self.merger.get_timeline.to_dict(orient="records")
-            ],
-            "participants": {
-                "target": {
-                    "company_id": self.merger.get_participants["target"].company.company_id,
-                    "company_name": self.merger.get_participants["target"].company.name,
-                },
-                "buyers": [
-                    {"company_id": buyer.company.company_id, "company_name": buyer.company.name}
-                    for buyer in self.merger.get_participants["buyers"]
-                ],
-                "sellers": [
-                    {"company_id": seller.company.company_id, "company_name": seller.company.name}
-                    for seller in self.merger.get_participants["sellers"]
-                ],
-            },
-            "consideration": {
-                "currency_name": self.merger.get_consideration["currency_name"],
-                "current_calculated_gross_total_transaction_value": self.merger.get_consideration[
-                    "current_calculated_gross_total_transaction_value"
-                ],
-                "current_calculated_implied_equity_value": self.merger.get_consideration[
-                    "current_calculated_implied_equity_value"
-                ],
-                "current_calculated_implied_enterprise_value": self.merger.get_consideration[
-                    "current_calculated_implied_enterprise_value"
-                ],
-                "details": [
-                    {
-                        "scenario": detail["scenario"],
-                        "subtype": detail["subtype"],
-                        "cash_or_cash_equivalent_per_target_share_unit": detail[
-                            "cash_or_cash_equivalent_per_target_share_unit"
-                        ],
-                        "number_of_target_shares_sought": detail["number_of_target_shares_sought"],
-                        "current_calculated_gross_value_of_consideration": detail[
-                            "current_calculated_gross_value_of_consideration"
-                        ],
-                    }
-                    for detail in self.merger.get_consideration["details"].to_dict(orient="records")
-                ],
-            },
-        }
-        self.assertEqual(ordered(expected_merger_info), ordered(merger_info))

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/domains/business_relationships/business_relationship_tools.py

@@ -38,7 +38,9 @@ class GetBusinessRelationshipFromIdentifiers(KfinanceTool):
     args_schema: Type[BaseModel] = GetBusinessRelationshipFromIdentifiersArgs
     accepted_permissions: set[Permission] | None = {Permission.RelationshipPermission}
 
-    def _run(self, identifiers: list[str], business_relationship: BusinessRelationshipType) -> dict:
+    def _run(
+        self, identifiers: list[str], business_relationship: BusinessRelationshipType
+    ) -> GetBusinessRelationshipFromIdentifiersResp:
         """Sample response:
 
         {
@@ -76,10 +78,8 @@ class GetBusinessRelationshipFromIdentifiers(KfinanceTool):
             api_client=api_client, tasks=tasks
         )
 
-        output_model = GetBusinessRelationshipFromIdentifiersResp(
+        return GetBusinessRelationshipFromIdentifiersResp(
             business_relationship=business_relationship,
             results=relationship_responses,
             errors=list(id_triple_resp.errors.values()),
         )
-
-        return output_model.model_dump(mode="json")

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/domains/business_relationships/tests/test_business_relationship_tools.py

@@ -8,6 +8,7 @@ from kfinance.domains.business_relationships.business_relationship_models import
 from kfinance.domains.business_relationships.business_relationship_tools import (
     GetBusinessRelationshipFromIdentifiers,
     GetBusinessRelationshipFromIdentifiersArgs,
+    GetBusinessRelationshipFromIdentifiersResp,
 )
 
 
@@ -27,21 +28,23 @@ class TestGetBusinessRelationshipFromIdentifiers:
                 {"company_id": 8182358, "company_name": "Eloqua, Inc."},
             ],
         }
-        expected_result = {
-            "business_relationship": "supplier",
-            "results": {
-                "SPGI": {
-                    "current": [{"company_id": "C_883103", "company_name": "CRISIL Limited"}],
-                    "previous": [
-                        {"company_id": "C_472898", "company_name": "Morgan Stanley"},
-                        {"company_id": "C_8182358", "company_name": "Eloqua, Inc."},
-                    ],
-                }
-            },
-            "errors": [
-                "No identification triple found for the provided identifier: NON-EXISTENT of type: ticker"
-            ],
-        }
+        expected_result = GetBusinessRelationshipFromIdentifiersResp.model_validate(
+            {
+                "business_relationship": "supplier",
+                "results": {
+                    "SPGI": {
+                        "current": [{"company_id": 883103, "company_name": "CRISIL Limited"}],
+                        "previous": [
+                            {"company_id": 472898, "company_name": "Morgan Stanley"},
+                            {"company_id": 8182358, "company_name": "Eloqua, Inc."},
+                        ],
+                    }
+                },
+                "errors": [
+                    "No identification triple found for the provided identifier: NON-EXISTENT of type: ticker"
+                ],
+            }
+        )
 
         requests_mock.get(
             url=f"https://kfinance.kensho.com/api/v1/relationship/{SPGI_COMPANY_ID}/supplier",
@@ -54,5 +57,4 @@ class TestGetBusinessRelationshipFromIdentifiers:
             business_relationship=BusinessRelationshipType.supplier,
         )
         resp = tool.run(args.model_dump(mode="json"))
-        resp["results"]["SPGI"]["previous"].sort(key=lambda x: x["company_id"])
         assert resp == expected_result

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/domains/capitalizations/capitalization_models.py

@@ -20,9 +20,9 @@ class DailyCapitalization(BaseModel):
     """DailyCapitalization represents market cap, TEV, and shares outstanding for a day"""
 
     date: date
-    market_cap: Money
-    tev: Money
-    shares_outstanding: Shares
+    market_cap: Money | None
+    tev: Money | None
+    shares_outstanding: Shares | None
 
 
 class Capitalizations(BaseModel):

{kensho_kfinance-3.2.5 → kensho_kfinance-3.2.7}/kfinance/domains/capitalizations/capitalization_tools.py

@@ -26,6 +26,7 @@ class GetCapitalizationFromIdentifiersArgs(ToolArgsWithIdentifiers):
 
 
 class GetCapitalizationFromIdentifiersResp(ToolRespWithErrors):
+    capitalization: Capitalization
     results: dict[str, Capitalizations]
 
 
@@ -50,13 +51,13 @@ class GetCapitalizationFromIdentifiers(KfinanceTool):
         capitalization: Capitalization,
         start_date: str | None = None,
         end_date: str | None = None,
-    ) -> dict:
+    ) -> GetCapitalizationFromIdentifiersResp:
         """Sample response:
 
         {
+            'capitalization': 'market_cap'
             'results': {
                 'SPGI': {
-                    'capitalizations': [
                         {'date': '2024-04-10', 'market_cap': {'value': '132766738270.00', 'unit': 'USD'}},
                         {'date': '2024-04-11', 'market_cap': {'value': '132416066761.00', 'unit': 'USD'}}
                     ]
@@ -100,7 +101,8 @@ class GetCapitalizationFromIdentifiers(KfinanceTool):
                 if capitalization is not Capitalization.shares_outstanding:
                     daily_capitalization.shares_outstanding = None
 
-        resp_model = GetCapitalizationFromIdentifiersResp(
-            results=capitalization_responses, errors=list(id_triple_resp.errors.values())
+        return GetCapitalizationFromIdentifiersResp(
+            capitalization=capitalization,
+            results=capitalization_responses,
+            errors=list(id_triple_resp.errors.values()),
         )
-        return resp_model.model_dump(mode="json", exclude_none=True)