kensho-kfinance 3.2.4__py3-none-any.whl → 4.0.0__py3-none-any.whl

kfinance/client/tests/test_objects.py

@@ -14,13 +14,13 @@ from kfinance.client.kfinance import (
     BusinessRelationships,
     Company,
     Earnings,
-    MergerOrAcquisition,
     ParticipantInMerger,
     Security,
     Ticker,
     TradingItem,
     Transcript,
 )
+from kfinance.client.models.response_models import PostResponse
 from kfinance.domains.business_relationships.business_relationship_models import (
     BusinessRelationshipType,
     RelationshipResponse,
@@ -28,8 +28,11 @@ from kfinance.domains.business_relationships.business_relationship_models import
 from kfinance.domains.capitalizations.capitalization_models import Capitalizations
 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.line_items.line_item_models import LineItemResp
+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
@@ -103,36 +106,103 @@ MOCK_COMPANY_DB = {
             }
         ),
         "line_items": {
-            "revenue": LineItemResponse.model_validate(
+            "revenue": LineItemResp.model_validate(
                 {
-                    "line_item": {
-                        "2019": "125843000000.000000",
-                        "2020": "143015000000.000000",
-                        "2021": "168088000000.000000",
-                        "2022": "198270000000.000000",
-                        "2023": "211915000000.000000",
-                    }
+                    "currency": "USD",
+                    "periods": {
+                        "CY2019": {
+                            "period_end_date": "2019-12-31",
+                            "num_months": 12,
+                            "line_item": {
+                                "name": "Revenue",
+                                "value": "125843000000.000000",
+                                "sources": [],
+                            },
+                        },
+                        "CY2020": {
+                            "period_end_date": "2020-12-31",
+                            "num_months": 12,
+                            "line_item": {
+                                "name": "Revenue",
+                                "value": "143015000000.000000",
+                                "sources": [],
+                            },
+                        },
+                        "CY2021": {
+                            "period_end_date": "2021-12-31",
+                            "num_months": 12,
+                            "line_item": {
+                                "name": "Revenue",
+                                "value": "168088000000.000000",
+                                "sources": [],
+                            },
+                        },
+                        "CY2022": {
+                            "period_end_date": "2022-12-31",
+                            "num_months": 12,
+                            "line_item": {
+                                "name": "Revenue",
+                                "value": "198270000000.000000",
+                                "sources": [],
+                            },
+                        },
+                        "CY2023": {
+                            "period_end_date": "2023-12-31",
+                            "num_months": 12,
+                            "line_item": {
+                                "name": "Revenue",
+                                "value": "211915000000.000000",
+                                "sources": [],
+                            },
+                        },
+                    },
                 }
             )
         },
         "segments": SegmentsResp.model_validate(
             {
-                "segments": {
-                    "2024": {
-                        "Intelligent Cloud": {
-                            "Operating Income": 49584000000.0,
-                            "Revenue": 105362000000.0,
-                        },
-                        "More Personal Computing": {
-                            "Operating Income": 19309000000.0,
-                            "Revenue": 62032000000.0,
-                        },
-                        "Productivity and Business Processes": {
-                            "Operating Income": 40540000000.0,
-                            "Revenue": 77728000000.0,
-                        },
+                "currency": "USD",
+                "periods": {
+                    "CY2024": {
+                        "period_end_date": "2024-12-31",
+                        "num_months": 12,
+                        "segments": [
+                            {
+                                "name": "Intelligent Cloud",
+                                "line_items": [
+                                    {
+                                        "name": "Operating Income",
+                                        "value": 49584000000.0,
+                                        "sources": [],
+                                    },
+                                    {"name": "Revenue", "value": 105362000000.0, "sources": []},
+                                ],
+                            },
+                            {
+                                "name": "More Personal Computing",
+                                "line_items": [
+                                    {
+                                        "name": "Operating Income",
+                                        "value": 19309000000.0,
+                                        "sources": [],
+                                    },
+                                    {"name": "Revenue", "value": 62032000000.0, "sources": []},
+                                ],
+                            },
+                            {
+                                "name": "Productivity and Business Processes",
+                                "line_items": [
+                                    {
+                                        "name": "Operating Income",
+                                        "value": 40540000000.0,
+                                        "sources": [],
+                                    },
+                                    {"name": "Revenue", "value": 77728000000.0, "sources": []},
+                                ],
+                            },
+                        ],
                     }
-                }
+                },
             }
         ),
         "advisors": {
@@ -191,12 +261,26 @@ MOCK_TRANSCRIPT_DB = {
 
 INCOME_STATEMENT = StatementsResp.model_validate(
     {
-        "statements": {
-            "2019": {
-                "Revenues": "125843000000.000000",
-                "Total Revenues": "125843000000.000000",
+        "currency": "USD",
+        "periods": {
+            "CY2019": {
+                "period_end_date": "2019-12-31",
+                "num_months": 12,
+                "statements": [
+                    {
+                        "name": "Income Statement",
+                        "line_items": [
+                            {"name": "Revenues", "value": "125843000000.000000", "sources": []},
+                            {
+                                "name": "Total Revenues",
+                                "value": "125843000000.000000",
+                                "sources": [],
+                            },
+                        ],
+                    }
+                ],
             }
-        }
+        },
     }
 )
 
@@ -254,39 +338,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",
+                    }
+                ],
+            },
+        }
+    )
 }
 
 
@@ -341,7 +427,7 @@ class MockKFinanceApiClient:
 
     def fetch_statement(
         self,
-        company_id,
+        company_ids,
         statement_type,
         period_type,
         start_year,
@@ -350,13 +436,26 @@ class MockKFinanceApiClient:
         end_quarter,
     ):
         """Get a statement"""
-        return INCOME_STATEMENT
+        return PostResponse[StatementsResp](
+            results={str(company_ids[0]): INCOME_STATEMENT}, errors={}
+        )
 
     def fetch_line_item(
-        self, company_id, line_item, period_type, start_year, end_year, start_quarter, end_quarter
+        self,
+        company_ids,
+        line_item,
+        period_type,
+        start_year,
+        end_year,
+        start_quarter,
+        end_quarter,
+        calendar_type=None,
+        num_periods=None,
+        num_periods_back=None,
     ):
         """Get a statement"""
-        return MOCK_COMPANY_DB[company_id]["line_items"][line_item]
+        line_item_resp = MOCK_COMPANY_DB[company_ids[0]]["line_items"][line_item]
+        return PostResponse[LineItemResp](results={str(company_ids[0]): line_item_resp}, errors={})
 
     def fetch_market_caps_tevs_and_shares_outstanding(
         self,
@@ -386,7 +485,7 @@ class MockKFinanceApiClient:
 
     def fetch_segments(
         self,
-        company_id,
+        company_ids,
         segment_type,
         period_type,
         start_year,
@@ -395,7 +494,9 @@ class MockKFinanceApiClient:
         end_quarter,
     ):
         """Get a segment"""
-        return MOCK_COMPANY_DB[company_id]["segments"]
+        return PostResponse[SegmentsResp](
+            results={str(company_ids[0]): MOCK_COMPANY_DB[company_ids[0]]["segments"]}, errors={}
+        )
 
     def fetch_companies_from_business_relationship(
         self, company_id: int, relationship_type: BusinessRelationshipType
@@ -519,10 +620,18 @@ class TestCompany(TestCase):
 
     def test_income_statement(self) -> None:
         """test income statement"""
+        # Extract statements data from the periods structure
+        periods_data = INCOME_STATEMENT.model_dump(mode="json")["periods"]
+        statements_data = {}
+        for period_key, period_data in periods_data.items():
+            period_statements = {}
+            for statement in period_data["statements"]:
+                for line_item in statement["line_items"]:
+                    period_statements[line_item["name"]] = line_item["value"]
+            statements_data[period_key] = period_statements
+
         expected_income_statement = (
-            pd.DataFrame(INCOME_STATEMENT.model_dump(mode="json")["statements"])
-            .apply(pd.to_numeric)
-            .replace(np.nan, None)
+            pd.DataFrame(statements_data).apply(pd.to_numeric).replace(np.nan, None)
         )
 
         income_statement = self.msft_company.company.income_statement()
@@ -530,11 +639,14 @@ class TestCompany(TestCase):
 
     def test_revenue(self) -> None:
         """test revenue"""
-        line_item_response: LineItemResponse = MOCK_COMPANY_DB[msft_company_id]["line_items"][
-            "revenue"
-        ]
+        line_item_response: LineItemResp = MOCK_COMPANY_DB[msft_company_id]["line_items"]["revenue"]
+
+        line_item_data = {}
+        for period_key, period_data in line_item_response.periods.items():
+            line_item_data[period_key] = period_data.line_item.value
+
         expected_revenue = (
-            pd.DataFrame({"line_item": line_item_response.line_item})
+            pd.DataFrame({"line_item": line_item_data})
             .transpose()
             .apply(pd.to_numeric)
             .replace(np.nan, None)
@@ -546,7 +658,7 @@ class TestCompany(TestCase):
     def test_business_segments(self) -> None:
         """test business statement"""
         expected_segments = MOCK_COMPANY_DB[msft_company_id]["segments"].model_dump(mode="json")[
-            "segments"
+            "periods"
         ]
 
         business_segment = self.msft_company.company.business_segments()
@@ -840,10 +952,18 @@ class TestTicker(TestCase):
 
     def test_income_statement(self) -> None:
         """test income statement"""
+        # Extract statements data from the periods structure
+        periods_data = INCOME_STATEMENT.model_dump(mode="json")["periods"]
+        statements_data = {}
+        for period_key, period_data in periods_data.items():
+            period_statements = {}
+            for statement in period_data["statements"]:
+                for line_item in statement["line_items"]:
+                    period_statements[line_item["name"]] = line_item["value"]
+            statements_data[period_key] = period_statements
+
         expected_income_statement = (
-            pd.DataFrame(INCOME_STATEMENT.model_dump(mode="json")["statements"])
-            .apply(pd.to_numeric)
-            .replace(np.nan, None)
+            pd.DataFrame(statements_data).apply(pd.to_numeric).replace(np.nan, None)
         )
 
         income_statement = self.msft_ticker_from_ticker.income_statement()
@@ -860,11 +980,14 @@ class TestTicker(TestCase):
 
     def test_revenue(self) -> None:
         """test revenue"""
-        line_item_response: LineItemResponse = MOCK_COMPANY_DB[msft_company_id]["line_items"][
-            "revenue"
-        ]
+        line_item_response: LineItemResp = MOCK_COMPANY_DB[msft_company_id]["line_items"]["revenue"]
+
+        line_item_data = {}
+        for period_key, period_data in line_item_response.periods.items():
+            line_item_data[period_key] = period_data.line_item.value
+
         expected_revenue = (
-            pd.DataFrame({"line_item": line_item_response.line_item})
+            pd.DataFrame({"line_item": line_item_data})
             .transpose()
             .apply(pd.to_numeric)
             .replace(np.nan, None)
@@ -1012,64 +1135,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))

kfinance/conftest.py

@@ -64,6 +64,16 @@ def mock_client(requests_mock: Mocker) -> Client:
             }
         },
     )
+    # Fetch a fake company
+    requests_mock.post(
+        url="https://kfinance.kensho.com/api/v1/ids",
+        additional_matcher=lambda req: req.json().get("identifiers") == ["C_1"],
+        json={
+            "data": {
+                "C_1": {"company_id": 1, "security_id": 1, "trading_item_id": 1},
+            },
+        },
+    )
     # Fetch SPGI and a non-existent company (which will include an error)
     requests_mock.post(
         url="https://kfinance.kensho.com/api/v1/ids",

kfinance/domains/business_relationships/business_relationship_tools.py

@@ -29,16 +29,27 @@ class GetBusinessRelationshipFromIdentifiersResp(BaseModel):
 class GetBusinessRelationshipFromIdentifiers(KfinanceTool):
     name: str = "get_business_relationship_from_identifiers"
     description: str = dedent("""
-        Get the current and previous company IDs that are relationship_type for a list of identifiers.
+        Get the current and previous companies that have a specified business relationship with each of the provided identifiers.
 
-        Example:
-        Query: "What are the previous borrowers of SPGI and JPM?"
-        Function: get_business_relationship_from_identifiers(identifiers=["SPGI", "JPM"], business_relationship=BusinessRelationshipType.borrower)
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+        - Results include both "current" (active) and "previous" (historical) relationships.
+
+        Examples:
+        Query: "Who are the current and previous suppliers of Intel?"
+        Function: get_business_relationship_from_identifiers(identifiers=["Intel"], business_relationship="supplier")
+
+        Query: "What are the borrowers of SPGI and JPM?"
+        Function: get_business_relationship_from_identifiers(identifiers=["SPGI", "JPM"], business_relationship="borrower")
+
+        Query: "Who are Dell's customers?"
+        Function: get_business_relationship_from_identifiers(identifiers=["Dell"], business_relationship="customer")
     """).strip()
     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 +87,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")

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

kfinance/domains/capitalizations/capitalization_models.py

@@ -2,7 +2,7 @@ from copy import deepcopy
 from datetime import date
 from typing import Any
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 from strenum import StrEnum
 
 from kfinance.client.models.decimal_with_unit import Money, Shares
@@ -20,14 +20,15 @@ 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):
     """Capitalizations represents market cap, TEV, and shares outstanding for a date range"""
 
+    model_config = ConfigDict(validate_by_name=True)
     capitalizations: list[DailyCapitalization] = Field(validation_alias="market_caps")
 
     @model_validator(mode="before")
@@ -65,7 +66,8 @@ class Capitalizations(BaseModel):
             currency = data["currency"]
             for capitalization in data["market_caps"]:
                 for key in ["market_cap", "tev"]:
-                    capitalization[key] = dict(unit=currency, value=capitalization[key])
+                    if capitalization[key] is not None:
+                        capitalization[key] = dict(unit=currency, value=capitalization[key])
         return data
 
     def model_dump_json_single_metric(