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

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

kfinance/client/meta_classes.py

@@ -85,22 +85,34 @@ class CompanyFunctionsMetaClass:
         except ValueError:
             return pd.DataFrame()
 
-        return (
-            pd.DataFrame(
-                self.kfinance_api_client.fetch_statement(
-                    company_id=self.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,
-                ).model_dump(mode="json")["statements"]
-            )
-            .apply(pd.to_numeric)
-            .replace(np.nan, None)
+        statement_response = self.kfinance_api_client.fetch_statement(
+            company_ids=[self.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,
         )
 
+        if not statement_response.results:
+            return pd.DataFrame()
+
+        # Get the first (and only) result
+        statement_resp = list(statement_response.results.values())[0]
+        periods = statement_resp.model_dump(mode="json")["periods"]
+
+        # Extract statements data from each period
+        statements_data = {}
+        for period_key, period_data in periods.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
+
+        return pd.DataFrame(statements_data).apply(pd.to_numeric).replace(np.nan, None)
+
     def income_statement(
         self,
         period_type: Optional[PeriodType] = None,
@@ -212,8 +224,8 @@ class CompanyFunctionsMetaClass:
         except ValueError:
             return pd.DataFrame()
 
-        line_item_response = self.kfinance_api_client.fetch_line_item(
-            company_id=self.company_id,
+        response = self.kfinance_api_client.fetch_line_item(
+            company_ids=[self.company_id],
             line_item=line_item,
             period_type=period_type,
             start_year=start_year,
@@ -221,8 +233,19 @@ class CompanyFunctionsMetaClass:
             start_quarter=start_quarter,
             end_quarter=end_quarter,
         )
+
+        if not response.results:
+            return pd.DataFrame()
+
+        # Get the first (and only) result
+        line_item_response = list(response.results.values())[0]
+
+        line_item_data = {}
+        for period_key, period_data in line_item_response.periods.items():
+            line_item_data[period_key] = period_data.line_item.value
+
         return (
-            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)
@@ -351,15 +374,22 @@ class CompanyFunctionsMetaClass:
         except ValueError:
             return {}
 
-        return self.kfinance_api_client.fetch_segments(
-            company_id=self.company_id,
+        segments_response = self.kfinance_api_client.fetch_segments(
+            company_ids=[self.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,
-        ).model_dump(mode="json")["segments"]
+        )
+
+        if not segments_response.results:
+            return {}
+
+        # Get the first (and only) result
+        segments_resp = list(segments_response.results.values())[0]
+        return segments_resp.model_dump(mode="json")["periods"]
 
     def business_segments(
         self,

kfinance/client/models/date_and_period_models.py

@@ -1,8 +1,26 @@
-from typing import TypedDict
+from datetime import date
+from typing import Annotated
 
+from pydantic import BaseModel, Field
 from strenum import StrEnum
 
 
+# Constrained integer types for period counts
+NumPeriods = Annotated[
+    int,
+    Field(ge=1, le=99, description="The number of periods to retrieve data for (1-99)"),
+]
+
+NumPeriodsBack = Annotated[
+    int,
+    Field(
+        ge=0,
+        le=99,
+        description="The end period of the data range expressed as number of periods back relative to the present period (0-99)",
+    ),
+]
+
+
 class PeriodType(StrEnum):
     """The period type"""
 
@@ -21,28 +39,35 @@ class Periodicity(StrEnum):
     year = "year"
 
 
-class YearAndQuarter(TypedDict):
+class EndpointType(StrEnum):
+    """The type of API endpoint to use for financial data retrieval"""
+
+    absolute = "absolute"
+    relative = "relative"
+
+
+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

kfinance/client/models/decimal_with_unit.py

@@ -2,7 +2,7 @@ from copy import deepcopy
 from decimal import Decimal
 from typing import Any
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 from typing_extensions import Self
 
 from kfinance.client.models.currency_models import ISO_CODE_TO_CURRENCY
@@ -20,11 +20,23 @@ class DecimalWithUnit(BaseModel):
     existing subclass like `Money` or `Shares` or create a new one.
     """
 
-    value: Decimal
+    value: Decimal = Field(allow_inf_nan=True)
     unit: str
     # exclude conventional_decimals from serialization
     conventional_decimals: int = Field(exclude=True)
 
+    @field_validator("value", mode="before")
+    @classmethod
+    def convert_none_to_nan(cls, v: Any) -> Any:
+        """Convert None values to NaN.
+
+        Price data can include None for open prices.
+        https://kfinance.kensho.com/api/v1/pricing/37284793/2003-01-01/2024-12-31/month/adjusted
+        """
+        if v is None:
+            return Decimal("NaN")
+        return v
+
     @model_validator(mode="after")
     def quantize_value(self) -> Self:
         """Quantize the value at the end of the deserialization.

kfinance/client/models/response_models.py

@@ -0,0 +1,33 @@
+from typing import Any, Callable, Dict, Generic, TypeAlias, TypeVar
+
+from pydantic import BaseModel, Field, model_serializer
+
+
+T = TypeVar("T", bound=BaseModel)
+
+Source: TypeAlias = dict[str, str]
+
+
+class RespWithErrors(BaseModel):
+    """A response with an `errors` field.
+
+    - `errors` is always the last field in the response.
+    - `errors` is only included if there is at least one error.
+    """
+
+    errors: dict[str, str] = Field(default_factory=dict)
+
+    @model_serializer(mode="wrap")
+    def serialize_model(self, handler: Callable) -> Dict[str, Any]:
+        """Make `errors` the last response field and only include if there is at least one error."""
+        data = handler(self)
+        errors = data.pop("errors")
+        if errors:
+            data["errors"] = errors
+        return data
+
+
+class PostResponse(RespWithErrors, Generic[T]):
+    """Generic response class that wraps results and errors from API calls."""
+
+    results: dict[str, T]

kfinance/client/models/tests/test_decimal_with_unit.py

@@ -32,6 +32,15 @@ class TestDecimalWithUnit:
         )
         assert dwu.value == expected_value
 
+    @pytest.mark.parametrize("value", [None, "NaN"])
+    def test_null_nan_allowed(self, value: str | None):
+        """
+        WHEN a DecimalWithUnit gets deserialized with None or "NaN"
+        THEN the deserialized value is Decimal("NaN")
+        """
+        dwu = DecimalWithUnit.model_validate(dict(value=value, conventional_decimals=1, unit="foo"))
+        assert dwu.value.is_nan()
+
 
 class TestMoney:
     @pytest.mark.parametrize("currency, expected_conventional_decimals", [("USD", 2), ("BIF", 0)])

kfinance/client/tests/test_batch_requests.py

@@ -212,11 +212,12 @@ class TestTradingItem(TestCase):
         )
         m.get("https://kfinance.kensho.com/api/v1/info/1002", status_code=400)
 
-        with self.assertRaises(requests.exceptions.HTTPError) as e:
-            companies = Companies(self.kfinance_api_client, [1001, 1002])
-            _ = companies.city
+        companies = Companies(self.kfinance_api_client, [1001, 1002])
+        result = companies.city
+        id_based_result = self.company_object_keys_as_company_id(result)
 
-        self.assertEqual(e.exception.response.status_code, 400)
+        expected_id_based_result = {1001: "Mock City A", 1002: None}
+        self.assertDictEqual(id_based_result, expected_id_based_result)
 
     @requests_mock.Mocker()
     def test_batch_request_500(self, m):