kensho-kfinance 3.0.2__tar.gz → 3.1.0__tar.gz

{kensho_kfinance-3.0.2/kensho_kfinance.egg-info → kensho_kfinance-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 3.0.2
+Version: 3.1.0
 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.0.2 → kensho_kfinance-3.1.0/kensho_kfinance.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 3.0.2
+Version: 3.1.0
 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.0.2 → kensho_kfinance-3.1.0}/kensho_kfinance.egg-info/SOURCES.txt

@@ -99,6 +99,7 @@ kfinance/domains/line_items/line_item_tools.py
 kfinance/domains/line_items/tests/__init__.py
 kfinance/domains/line_items/tests/test_line_item_tools.py
 kfinance/domains/mergers_and_acquisitions/__init__.py
+kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_models.py
 kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_tools.py
 kfinance/domains/mergers_and_acquisitions/tests/__init__.py
 kfinance/domains/mergers_and_acquisitions/tests/test_merger_and_acquisition_tools.py

{kensho_kfinance-3.0.2 → kensho_kfinance-3.1.0}/kfinance/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v3.1.0
+- Use unified endpoint for company resolution
+
+## v3.0.3
+- Add LineItemResponse model
+
 ## v3.0.2
 - Add kfinance.mcp back to simplify transition to 3.0
 
@@ -25,7 +31,7 @@
 - Add transcript permission and update accepted_permissions type to set[Permission]
 
 ## v2.6.3
-- Bump urllib3 to 2.5 to  address CVEs
+- Bump urllib3 to 2.5 to address CVEs
 
 ## v2.6.2
  - Safely check for incomplete merger information

{kensho_kfinance-3.0.2 → kensho_kfinance-3.1.0}/kfinance/client/fetch.py

@@ -17,11 +17,14 @@ from kfinance.domains.business_relationships.business_relationship_models import
     RelationshipResponse,
 )
 from kfinance.domains.capitalizations.capitalization_models import Capitalizations
-from kfinance.domains.companies.company_models import IdentificationTriple
+from kfinance.domains.companies.company_models import IdentificationTriple, UnifiedIdTripleResponse
 from kfinance.domains.competitors.competitor_models import CompetitorResponse, CompetitorSource
 from kfinance.domains.earnings.earning_models import EarningsCallResp
-from kfinance.domains.prices.price_models import PriceHistory
-from kfinance.domains.segments.segment_models import SegmentType
+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.prices.price_models import HistoryMetadataResp, PriceHistory
+from kfinance.domains.segments.segment_models import SegmentsResp, SegmentType
+from kfinance.domains.statements.statement_models import StatementsResp
 
 
 # version.py gets autogenerated by setuptools-scm and is not available
@@ -226,7 +229,7 @@ class KFinanceApiClient:
         finally:
             self._endpoint_tracker_queue = None
 
-    def fetch(self, url: str) -> dict:
+    def fetch(self, url: str, method: str = "GET", request_body: dict | None = None) -> dict:
         """Does the request and auth"""
 
         # _endpoint_tracker_queue will only be initialized if inside the endpoint_tracker context manager
@@ -244,9 +247,11 @@ class KFinanceApiClient:
                 {"Kfinance-Batch-Id": self._batch_id, "Kfinance-Batch-Size": self._batch_size}
             )
 
-        response = requests.get(
-            url,
+        response = requests.request(
+            method=method,
+            url=url,
             headers=headers,
+            json=request_body,
             timeout=60,
         )
         response.raise_for_status()
@@ -289,6 +294,12 @@ class KFinanceApiClient:
         url = f"{self.url_base}trading_items/{security_id}/primary"
         return self.fetch(url)
 
+    def unified_fetch_id_triples(self, identifiers: list[str]) -> UnifiedIdTripleResponse:
+        """Resolve one or more identifiers to id triples using the unified (/ids) endpoint."""
+        url = f"{self.url_base}ids"
+        resp = self.fetch(url=url, method="POST", request_body=dict(identifiers=identifiers))
+        return UnifiedIdTripleResponse.model_validate(resp)
+
     def fetch_trading_items(self, security_id: int) -> dict:
         """Get the list of trading items of a security."""
         url = f"{self.url_base}trading_items/{security_id}"
@@ -312,10 +323,10 @@ class KFinanceApiClient:
         )
         return PriceHistory.model_validate(self.fetch(url))
 
-    def fetch_history_metadata(self, trading_item_id: int) -> dict[str, str]:
+    def fetch_history_metadata(self, trading_item_id: int) -> HistoryMetadataResp:
         """Get the pricing history metadata."""
         url = f"{self.url_base}pricing/{trading_item_id}/metadata"
-        return self.fetch(url)
+        return HistoryMetadataResp.model_validate(self.fetch(url))
 
     def fetch_market_caps_tevs_and_shares_outstanding(
         self,
@@ -340,7 +351,7 @@ class KFinanceApiClient:
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
         end_quarter: Optional[int] = None,
-    ) -> dict:
+    ) -> SegmentsResp:
         """Get a specified segment type for a specified duration."""
         url = (
             f"{self.url_base}segments/{company_id}/{segment_type}/"
@@ -350,7 +361,7 @@ class KFinanceApiClient:
             f"{start_quarter if start_quarter is not None else 'none'}/"
             f"{end_quarter if end_quarter is not None else 'none'}"
         )
-        return self.fetch(url)
+        return SegmentsResp.model_validate(self.fetch(url))
 
     def fetch_price_chart(
         self,
@@ -389,7 +400,7 @@ class KFinanceApiClient:
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
         end_quarter: Optional[int] = None,
-    ) -> dict:
+    ) -> StatementsResp:
         """Get a specified financial statement for a specified duration."""
         url = (
             f"{self.url_base}statements/{company_id}/{statement_type}/"
@@ -399,7 +410,7 @@ class KFinanceApiClient:
             f"{start_quarter if start_quarter is not None else 'none'}/"
             f"{end_quarter if end_quarter is not None else 'none'}"
         )
-        return self.fetch(url)
+        return StatementsResp.model_validate(self.fetch(url))
 
     def fetch_line_item(
         self,
@@ -410,7 +421,7 @@ class KFinanceApiClient:
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
         end_quarter: Optional[int] = None,
-    ) -> dict:
+    ) -> LineItemResponse:
         """Get a specified financial line item for a specified duration."""
         url = (
             f"{self.url_base}line_item/{company_id}/{line_item}/"
@@ -420,7 +431,7 @@ class KFinanceApiClient:
             f"{start_quarter if start_quarter is not None else 'none'}/"
             f"{end_quarter if end_quarter is not None else 'none'}"
         )
-        return self.fetch(url)
+        return LineItemResponse.model_validate(self.fetch(url))
 
     def fetch_info(self, company_id: int) -> dict:
         """Get the company info."""
@@ -603,17 +614,16 @@ class KFinanceApiClient:
     def fetch_mergers_for_company(
         self,
         company_id: int,
-    ) -> dict[str, list[dict[str, int | str]]]:
+    ) -> MergersResp:
         """Fetches the mergers and acquisitions the given company was involved in.
 
-        Returns a dictionary of shape {"target", [{"transaction_id": <transaction_id>, "merger_title": <merger short title>}], "buyer": [...], "seller": [...]}
         :param company_id: The company ID to filter on.
         :type company_id: int
-        :return: A dictionary containing transaction IDs and 'merger titles' for each of the three kinds of roles the given company could be party to.
-        :rtype: dict[str, list[dict[str, int | str]]]
+        :return: A MergersResp, containing transaction IDs, closed_date, and 'merger titles' for each of the three kinds of roles the given company could be party to.
+        :rtype: MergersResp
         """
         url = f"{self.url_base}mergers/{company_id}"
-        return self.fetch(url)
+        return MergersResp.model_validate(self.fetch(url))
 
     def fetch_merger_info(
         self,

{kensho_kfinance-3.0.2 → kensho_kfinance-3.1.0}/kfinance/client/kfinance.py

@@ -38,7 +38,7 @@ from kfinance.client.models.date_and_period_models import (
 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.prices.price_models import HistoryMetadata, PriceHistory
+from kfinance.domains.prices.price_models import HistoryMetadataResp, PriceHistory
 
 
 if TYPE_CHECKING:
@@ -78,7 +78,7 @@ class TradingItem:
         self.trading_item_id = trading_item_id
 
         self._ticker: str | None = None
-        self._history_metadata: HistoryMetadata | None = None
+        self._history_metadata: HistoryMetadataResp | None = None
 
     def __str__(self) -> str:
         """String representation for the company object"""
@@ -105,20 +105,15 @@ class TradingItem:
         return trading_item
 
     @property
-    def history_metadata(self) -> HistoryMetadata:
+    def history_metadata(self) -> HistoryMetadataResp:
         """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
         """
         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(),
+            self._history_metadata = self.kfinance_api_client.fetch_history_metadata(
+                self.trading_item_id
             )
         return self._history_metadata
 
@@ -129,7 +124,7 @@ class TradingItem:
         :return: The exchange code of the trading item.
         :rtype: str
         """
-        return self.history_metadata["exchange_name"]
+        return self.history_metadata.exchange_name
 
     def history(
         self,
@@ -635,7 +630,7 @@ class Company(CompanyFunctionsMetaClass):
         if self._mergers_for_company is None:
             mergers_for_company = self.kfinance_api_client.fetch_mergers_for_company(
                 company_id=self.company_id
-            )
+            ).model_dump(mode="json")
             output: dict = {}
             for literal in ["target", "buyer", "seller"]:
                 output[literal] = MergersAndAcquisitions(
@@ -872,7 +867,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         self._primary_security: Security | None = None
         self._primary_trading_item: TradingItem | None = None
         self._company: Company | None = None
-        self._history_metadata: HistoryMetadata | None = None
+        self._history_metadata: HistoryMetadataResp | None = None
 
     @property
     def id_triple(self) -> IdentificationTriple:
@@ -946,6 +941,8 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         :return: the CIQ security id
         :rtype: int
         """
+        if self.id_triple.security_id is None:
+            raise ValueError(f"Ticker {self.ticker} does not have a security_id.")
         return self.id_triple.security_id
 
     @property
@@ -955,6 +952,8 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         :return: the CIQ trading item id
         :rtype: int
         """
+        if self.id_triple.trading_item_id is None:
+            raise ValueError(f"Ticker {self.ticker} does not have a trading_item_id.")
         return self.id_triple.trading_item_id
 
     @property
@@ -1158,7 +1157,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         return self.company.earnings_call_datetimes
 
     @property
-    def history_metadata(self) -> HistoryMetadata:
+    def history_metadata(self) -> HistoryMetadataResp:
         """Get information about exchange and quotation
 
         :return: A dict containing data about the currency, symbol, exchange, type of instrument, and the first trading date
@@ -1166,9 +1165,9 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         """
         metadata = self.primary_trading_item.history_metadata
         if self.exchange_code is None:
-            self.exchange_code = metadata["exchange_name"]
+            self.exchange_code = metadata.exchange_name
         if self._ticker is None:
-            self._ticker = metadata["symbol"]
+            self._ticker = metadata.symbol
         return metadata
 
     @property
@@ -1176,7 +1175,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         """Get the ticker if it isn't available from initialization"""
         if self._ticker is not None:
             return self._ticker
-        return self.history_metadata["symbol"]
+        return self.history_metadata.symbol
 
     def history(
         self,
@@ -1870,7 +1869,7 @@ class Client:
         """
         mergers_for_company = self.kfinance_api_client.fetch_mergers_for_company(
             company_id=company_id
-        )
+        ).model_dump(mode="json")
         output: dict = {}
         for literal in ["target", "buyer", "seller"]:
             output[literal] = MergersAndAcquisitions(

{kensho_kfinance-3.0.2 → kensho_kfinance-3.1.0}/kfinance/client/meta_classes.py

@@ -85,7 +85,7 @@ class CompanyFunctionsMetaClass:
                     end_year=end_year,
                     start_quarter=start_quarter,
                     end_quarter=end_quarter,
-                )["statements"]
+                ).model_dump(mode="json")["statements"]
             )
             .apply(pd.to_numeric)
             .replace(np.nan, None)
@@ -202,18 +202,17 @@ class CompanyFunctionsMetaClass:
         except ValueError:
             return pd.DataFrame()
 
+        line_item_response = self.kfinance_api_client.fetch_line_item(
+            company_id=self.company_id,
+            line_item=line_item,
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        )
         return (
-            pd.DataFrame(
-                self.kfinance_api_client.fetch_line_item(
-                    company_id=self.company_id,
-                    line_item=line_item,
-                    period_type=period_type,
-                    start_year=start_year,
-                    end_year=end_year,
-                    start_quarter=start_quarter,
-                    end_quarter=end_quarter,
-                )
-            )
+            pd.DataFrame({"line_item": line_item_response.line_item})
             .transpose()
             .apply(pd.to_numeric)
             .replace(np.nan, None)
@@ -350,7 +349,7 @@ class CompanyFunctionsMetaClass:
             end_year=end_year,
             start_quarter=start_quarter,
             end_quarter=end_quarter,
-        )["segments"]
+        ).model_dump(mode="json")["segments"]
 
     def business_segments(
         self,

{kensho_kfinance-3.0.2 → kensho_kfinance-3.1.0}/kfinance/client/tests/test_fetch.py

@@ -83,16 +83,20 @@ class TestFetchItem(TestCase):
         expected_fetch_url = (
             f"{self.kfinance_api_client.url_base}pricing/{trading_item_id}/metadata"
         )
-        self.kfinance_api_client.fetch_history_metadata(trading_item_id=trading_item_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_history_metadata(trading_item_id=trading_item_id)
         self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
 
     def test_fetch_statement(self) -> None:
         company_id = 21719
         statement_type = "BS"
         expected_fetch_url = f"{self.kfinance_api_client.url_base}statements/{company_id}/{statement_type}/none/none/none/none/none"
-        self.kfinance_api_client.fetch_statement(
-            company_id=company_id, statement_type=statement_type
-        )
+        # 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_statement(
+                company_id=company_id, statement_type=statement_type
+            )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
         period_type = PeriodType.quarterly
         start_year = 2024
@@ -100,22 +104,26 @@ class TestFetchItem(TestCase):
         start_quarter = 1
         end_quarter = 4
         expected_fetch_url = f"{self.kfinance_api_client.url_base}statements/{company_id}/{statement_type}/{period_type.value}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
-        self.kfinance_api_client.fetch_statement(
-            company_id=company_id,
-            statement_type=statement_type,
-            period_type=period_type,
-            start_year=start_year,
-            end_year=end_year,
-            start_quarter=start_quarter,
-            end_quarter=end_quarter,
-        )
+        # 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_statement(
+                company_id=company_id,
+                statement_type=statement_type,
+                period_type=period_type,
+                start_year=start_year,
+                end_year=end_year,
+                start_quarter=start_quarter,
+                end_quarter=end_quarter,
+            )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
     def test_fetch_line_item(self) -> None:
         company_id = 21719
         line_item = "cash"
         expected_fetch_url = f"{self.kfinance_api_client.url_base}line_item/{company_id}/{line_item}/none/none/none/none/none"
-        self.kfinance_api_client.fetch_line_item(company_id=company_id, line_item=line_item)
+        # 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_line_item(company_id=company_id, line_item=line_item)
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
         period_type = PeriodType.quarterly
         start_year = 2024
@@ -123,15 +131,18 @@ class TestFetchItem(TestCase):
         start_quarter = 1
         end_quarter = 4
         expected_fetch_url = f"{self.kfinance_api_client.url_base}line_item/{company_id}/{line_item}/{period_type.value}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
-        self.kfinance_api_client.fetch_line_item(
-            company_id=company_id,
-            line_item=line_item,
-            period_type=period_type,
-            start_year=start_year,
-            end_year=end_year,
-            start_quarter=start_quarter,
-            end_quarter=end_quarter,
-        )
+
+        # 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_line_item(
+                company_id=company_id,
+                line_item=line_item,
+                period_type=period_type,
+                start_year=start_year,
+                end_year=end_year,
+                start_quarter=start_quarter,
+                end_quarter=end_quarter,
+            )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
     def test_fetch_info(self) -> None:
@@ -262,7 +273,10 @@ class TestFetchItem(TestCase):
         company_id = 21719
         segment_type = "business"
         expected_fetch_url = f"{self.kfinance_api_client.url_base}segments/{company_id}/{segment_type}/none/none/none/none/none"
-        self.kfinance_api_client.fetch_segments(company_id=company_id, segment_type=segment_type)
+        with pytest.raises(ValidationError):
+            self.kfinance_api_client.fetch_segments(
+                company_id=company_id, segment_type=segment_type
+            )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
         period_type = PeriodType.quarterly
         start_year = 2023
@@ -270,21 +284,24 @@ class TestFetchItem(TestCase):
         start_quarter = 1
         end_quarter = 4
         expected_fetch_url = f"{self.kfinance_api_client.url_base}segments/{company_id}/{segment_type}/{period_type.value}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
-        self.kfinance_api_client.fetch_segments(
-            company_id=company_id,
-            segment_type=segment_type,
-            period_type=period_type,
-            start_year=start_year,
-            end_year=end_year,
-            start_quarter=start_quarter,
-            end_quarter=end_quarter,
-        )
+        with pytest.raises(ValidationError):
+            self.kfinance_api_client.fetch_segments(
+                company_id=company_id,
+                segment_type=segment_type,
+                period_type=period_type,
+                start_year=start_year,
+                end_year=end_year,
+                start_quarter=start_quarter,
+                end_quarter=end_quarter,
+            )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
     def test_fetch_mergers_for_company(self) -> None:
         company_id = 21719
         expected_fetch_url = f"{self.kfinance_api_client.url_base}mergers/{company_id}"
-        self.kfinance_api_client.fetch_mergers_for_company(company_id=company_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_mergers_for_company(company_id=company_id)
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
     def test_fetch_merger_info(self) -> None: