kensho-kfinance 2.7.0__py3-none-any.whl → 2.8.0__py3-none-any.whl

kfinance/models/price_models.py

@@ -0,0 +1,70 @@
+from copy import deepcopy
+from datetime import date
+from typing import Any, TypedDict
+
+from pydantic import BaseModel, model_validator
+
+from kfinance.decimal_with_unit import Money, Shares
+
+
+class HistoryMetadata(TypedDict):
+    currency: str
+    symbol: str
+    exchange_name: str
+    instrument_type: str
+    first_trade_date: date
+
+
+class Prices(BaseModel):
+    """Prices represents prices for a stock for a specific "date".
+
+    I'm putting "date" in quotes because dates can be daily ("2024-01-01"),
+    weekly ("2024 Week 2"), monthly ("January 2024"), or annual ("2024").
+    """
+
+    date: str
+    open: Money
+    high: Money
+    low: Money
+    close: Money
+    volume: Shares
+
+
+class PriceHistory(BaseModel):
+    """PriceHistory represents stock prices over a time range."""
+
+    prices: list[Prices]
+
+    @model_validator(mode="before")
+    @classmethod
+    def inject_currency_into_data(cls, data: Any) -> Any:
+        """Inject the currency into each open/high/low/close price.
+
+        The price history response only includes the currency as a top level element.
+        However, the Prices model expects the unit to be included with each price.
+        Before:
+            {
+                "date": "2024-06-25",
+                "open": "445.790000",
+                "high": "449.240000",
+                ...
+            }
+        After:
+            {
+                "date": "2024-06-25",
+                "open": {"value": "445.790000", "unit": "USD"},
+                "high": {"value": "449.240000", "unit": "USD"},
+                ...
+            }
+
+        Note: Volume does not need the unit injected because the Shares class
+            already has "Shares" encoded. However, currencies differ between companies,
+            so we need to inject that information.
+        """
+        if isinstance(data, dict) and "currency" in data:
+            data = deepcopy(data)
+            currency = data["currency"]
+            for capitalization in data["prices"]:
+                for key in ["open", "high", "low", "close"]:
+                    capitalization[key] = dict(unit=currency, value=capitalization[key])
+        return data

kfinance/models/segment_models.py

@@ -0,0 +1,8 @@
+from strenum import StrEnum
+
+
+class SegmentType(StrEnum):
+    """The type of segment"""
+
+    business = "business"
+    geographic = "geographic"

kfinance/models/statement_models.py

@@ -0,0 +1,9 @@
+from strenum import StrEnum
+
+
+class StatementType(StrEnum):
+    """The type of financial statement"""
+
+    balance_sheet = "balance_sheet"
+    income_statement = "income_statement"
+    cashflow = "cashflow"

kfinance/tests/test_batch_requests.py

@@ -1,18 +1,19 @@
 from concurrent.futures import ThreadPoolExecutor
+from decimal import Decimal
 import time
 from typing import Any, Dict
 from unittest import TestCase
 from unittest.mock import PropertyMock, patch
 
-import numpy as np
-import pandas as pd
 import pytest
 import requests
 import requests_mock
 
 from kfinance.batch_request_handling import MAX_WORKERS_CAP
+from kfinance.decimal_with_unit import Money, Shares
 from kfinance.fetch import KFinanceApiClient
-from kfinance.kfinance import Companies, Company, Ticker, TradingItems
+from kfinance.kfinance import Companies, Company, Ticker, TradingItem, TradingItems
+from kfinance.models.price_models import PriceHistory, Prices
 
 
 @pytest.fixture(autouse=True)
@@ -77,46 +78,75 @@ class TestTradingItem(TestCase):
         m.get(
             "https://kfinance.kensho.com/api/v1/pricing/2/none/none/day/adjusted",
             json={
+                "currency": "USD",
                 "prices": [
-                    {"date": "2024-01-01", "close": "100.000000"},
-                    {"date": "2024-01-02", "close": "101.000000"},
-                ]
+                    {
+                        "date": "2024-04-11",
+                        "open": "1.0000",
+                        "high": "2.0000",
+                        "low": "3.0000",
+                        "close": "4.0000",
+                        "volume": "5",
+                    },
+                ],
             },
         )
         m.get(
             "https://kfinance.kensho.com/api/v1/pricing/3/none/none/day/adjusted",
             json={
+                "currency": "USD",
                 "prices": [
-                    {"date": "2024-01-01", "close": "200.000000"},
-                    {"date": "2024-01-02", "close": "201.000000"},
-                ]
+                    {
+                        "date": "2024-04-11",
+                        "open": "5.0000",
+                        "high": "6.0000",
+                        "low": "7.0000",
+                        "close": "8.0000",
+                        "volume": "9",
+                    },
+                ],
             },
         )
 
-        trading_items = TradingItems(self.kfinance_api_client, [2, 3])
+        trading_item_2 = TradingItem(
+            kfinance_api_client=self.kfinance_api_client, trading_item_id=2
+        )
+        trading_item_3 = TradingItem(
+            kfinance_api_client=self.kfinance_api_client, trading_item_id=3
+        )
 
-        result = trading_items.history()
-        expected_dictionary_based_result = {
-            2: [
-                {"date": "2024-01-01", "close": "100.000000"},
-                {"date": "2024-01-02", "close": "101.000000"},
-            ],
-            3: [
-                {"date": "2024-01-01", "close": "200.000000"},
-                {"date": "2024-01-02", "close": "201.000000"},
-            ],
+        trading_items = TradingItems(
+            self.kfinance_api_client, trading_items=[trading_item_2, trading_item_3]
+        )
+        expected_result = {
+            trading_item_2: PriceHistory(
+                prices=[
+                    Prices(
+                        date="2024-04-11",
+                        open=Money(value=Decimal("1.00"), unit="USD", conventional_decimals=2),
+                        high=Money(value=Decimal("2.00"), unit="USD", conventional_decimals=2),
+                        low=Money(value=Decimal("3.00"), unit="USD", conventional_decimals=2),
+                        close=Money(value=Decimal("4.00"), unit="USD", conventional_decimals=2),
+                        volume=Shares(value=Decimal("5"), unit="Shares", conventional_decimals=0),
+                    )
+                ]
+            ),
+            trading_item_3: PriceHistory(
+                prices=[
+                    Prices(
+                        date="2024-04-11",
+                        open=Money(value=Decimal("5.00"), unit="USD", conventional_decimals=2),
+                        high=Money(value=Decimal("6.00"), unit="USD", conventional_decimals=2),
+                        low=Money(value=Decimal("7.00"), unit="USD", conventional_decimals=2),
+                        close=Money(value=Decimal("8.00"), unit="USD", conventional_decimals=2),
+                        volume=Shares(value=Decimal("9"), unit="Shares", conventional_decimals=0),
+                    )
+                ]
+            ),
         }
-        self.assertEqual(len(result), len(expected_dictionary_based_result))
-
-        for k, v in result.items():
-            trading_item_id = k.trading_item_id
-            pd.testing.assert_frame_equal(
-                v,
-                pd.DataFrame(expected_dictionary_based_result[trading_item_id])
-                .set_index("date")
-                .apply(pd.to_numeric)
-                .replace(np.nan, None),
-            )
+
+        result = trading_items.history()
+        assert result == expected_result
 
     @requests_mock.Mocker()
     def test_large_batch_request_property(self, m):

kfinance/tests/test_client.py

@@ -2,8 +2,8 @@ from unittest.mock import Mock
 
 import pytest
 
-from kfinance.constants import Permission
 from kfinance.kfinance import Client
+from kfinance.models.permission_models import Permission
 from kfinance.tool_calling import (
     GetBusinessRelationshipFromIdentifier,
     GetEarnings,

kfinance/tests/test_decimal_with_unit.py

@@ -0,0 +1,60 @@
+from decimal import Decimal
+from typing import Any
+
+import pytest
+
+from kfinance.decimal_with_unit import DecimalWithUnit, Money, Shares
+
+
+class TestDecimalWithUnit:
+    @pytest.mark.parametrize(
+        "conventional_decimals, input, expected_value",
+        [
+            pytest.param(2, "0.10", Decimal("0.10"), id="input matches conventional decimals"),
+            pytest.param(
+                1, "0.10", Decimal("0.1"), id="input more precise than conventional decimals"
+            ),
+            pytest.param(
+                3, "0.10", Decimal("0.100"), id="input less precise than conventional decimals"
+            ),
+            pytest.param(1, "0.11", Decimal("0.1"), id="input gets rounded if necessary"),
+        ],
+    )
+    def test_quantize_value(
+        self, conventional_decimals: int, input: str, expected_value: Decimal
+    ) -> None:
+        """
+        WHEN a DecimalWithUnit gets deserialized
+        THEN the value gets quantized to the conventional_decimals
+        """
+        dwu = DecimalWithUnit.model_validate(
+            dict(value=input, conventional_decimals=conventional_decimals, unit="foo")
+        )
+        assert dwu.value == expected_value
+
+
+class TestMoney:
+    @pytest.mark.parametrize("currency, expected_conventional_decimals", [("USD", 2), ("BIF", 0)])
+    def test_conventional_decimals_injection(
+        self, currency: str, expected_conventional_decimals: int
+    ) -> None:
+        """
+        GIVEN a value and unit dict
+        WHEN we deserialize the dict into a Money object
+        THEN the conventional decimals for the currency get injected.
+        """
+
+        money = Money.model_validate({"value": 1, "unit": currency})
+        assert money.conventional_decimals == expected_conventional_decimals
+
+
+class TestShares:
+    @pytest.mark.parametrize("input", ["1", 1, Decimal(1), {"value": 1}])
+    def test_share_deserialization(self, input: Any):
+        """
+        GIVEN a str, int, decimal, or dict with value key
+        WHEN we deserialize the input into a Shares object
+        THEN all of these inputs are accepted.
+        """
+        shares = Shares.model_validate(input)
+        assert shares.value == Decimal(1)

kfinance/tests/test_example_notebook.py

@@ -118,6 +118,7 @@ def test_run_notebook(jupyter_kernel_name: str):
         )
 
         prices_resp = {
+            "currency": "USD",
             "prices": [
                 {
                     "date": "2024-05-20",

kfinance/tests/test_fetch.py

@@ -1,12 +1,14 @@
 from unittest import TestCase
 from unittest.mock import MagicMock
 
+from pydantic import ValidationError
 import pytest
 from requests_mock import Mocker
 
-from kfinance.constants import BusinessRelationshipType, Periodicity, PeriodType
 from kfinance.fetch import KFinanceApiClient
 from kfinance.kfinance import Client
+from kfinance.models.business_relationship_models import BusinessRelationshipType
+from kfinance.models.date_and_period_models import Periodicity, PeriodType
 from kfinance.pydantic_models import (
     CompanyIdAndName,
     RelationshipResponse,
@@ -53,21 +55,28 @@ class TestFetchItem(TestCase):
         expected_fetch_url = (
             f"{self.kfinance_api_client.url_base}pricing/{trading_item_id}/none/none/none/adjusted"
         )
-        self.kfinance_api_client.fetch_history(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(trading_item_id=trading_item_id)
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
+    def test_fetch_history_with_dates(self) -> None:
+        trading_item_id = 2629108
         start_date = "2025-01-01"
         end_date = "2025-01-31"
         is_adjusted = False
         periodicity = Periodicity.day
         expected_fetch_url = f"{self.kfinance_api_client.url_base}pricing/{trading_item_id}/{start_date}/{end_date}/{periodicity.value}/unadjusted"
-        self.kfinance_api_client.fetch_history(
-            trading_item_id=trading_item_id,
-            is_adjusted=is_adjusted,
-            start_date=start_date,
-            end_date=end_date,
-            periodicity=periodicity,
-        )
+
+        # 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(
+                trading_item_id=trading_item_id,
+                is_adjusted=is_adjusted,
+                start_date=start_date,
+                end_date=end_date,
+                periodicity=periodicity,
+            )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
     def test_fetch_history_metadata(self) -> None:
@@ -310,9 +319,11 @@ class TestMarketCap:
         expected_fetch_url = (
             f"{client.url_base}market_cap/{company_id}/{start_date_url}/{end_date_url}"
         )
-        client.fetch_market_caps_tevs_and_shares_outstanding(
-            company_id=company_id, start_date=start_date, end_date=end_date
-        )
+        # Validation error is ok, we only care that the function was called with the correct url
+        with pytest.raises(ValidationError):
+            client.fetch_market_caps_tevs_and_shares_outstanding(
+                company_id=company_id, start_date=start_date, end_date=end_date
+            )
         client.fetch.assert_called_with(expected_fetch_url)
 
     def test_fetch_permissions(self):

kfinance/tests/test_models/test_capitalization_models.py

@@ -0,0 +1,83 @@
+from datetime import date
+from decimal import Decimal
+
+from kfinance.decimal_with_unit import Money, Shares
+from kfinance.models.capitalization_models import (
+    Capitalization,
+    Capitalizations,
+    DailyCapitalization,
+)
+
+
+class TestCapitalizations:
+    api_resp = {
+        "currency": "USD",
+        "market_caps": [
+            {
+                "date": "2024-06-24",
+                "market_cap": "139231113000.000000",
+                "tev": "153942113000.000000",
+                "shares_outstanding": 312900000,
+            },
+            {
+                "date": "2024-06-25",
+                "market_cap": "140423262000.000000",
+                "tev": "155134262000.000000",
+                "shares_outstanding": 312900000,
+            },
+        ],
+    }
+
+    def test_capitalizations_deserialization(self) -> None:
+        """
+        GIVEN a capitalizations API response
+        WHEN we deserialize the response into a Capitalizations object
+        THEN the deserialization succeeds and returns the expected value.
+        """
+
+        expected_capitalizations = Capitalizations.model_construct(
+            capitalizations=[
+                DailyCapitalization(
+                    date=date(2024, 6, 24),
+                    market_cap=Money(
+                        value=Decimal("139231113000.00"), unit="USD", conventional_decimals=2
+                    ),
+                    tev=Money(
+                        value=Decimal("153942113000.00"), unit="USD", conventional_decimals=2
+                    ),
+                    shares_outstanding=Shares(
+                        value=Decimal("312900000"), unit="Shares", conventional_decimals=0
+                    ),
+                ),
+                DailyCapitalization(
+                    date=date(2024, 6, 25),
+                    market_cap=Money(
+                        value=Decimal("140423262000.00"), unit="USD", conventional_decimals=2
+                    ),
+                    tev=Money(
+                        value=Decimal("155134262000.00"), unit="USD", conventional_decimals=2
+                    ),
+                    shares_outstanding=Shares(
+                        value=Decimal("312900000"), unit="Shares", conventional_decimals=0
+                    ),
+                ),
+            ]
+        )
+
+        assert Capitalizations.model_validate(self.api_resp) == expected_capitalizations
+
+    def test_single_attribute_serialization(self):
+        """
+        GIVEN a Capitalizations object
+        WHEN we only want to jsonify a single attribute like market_cap
+        THEN that attribute gets returned in an LLM-readable, jsonifyable dict format
+        """
+        expected_serialization = {
+            "market_cap": [
+                {"2024-06-24": {"unit": "USD", "value": "139231113000.00"}},
+                {"2024-06-25": {"unit": "USD", "value": "140423262000.00"}},
+            ]
+        }
+        capitalizations = Capitalizations.model_validate(self.api_resp)
+        serialized = capitalizations.jsonify_single_attribute(Capitalization.market_cap)
+        assert serialized == expected_serialization

kfinance/tests/test_models/test_price_models.py

@@ -0,0 +1,58 @@
+from decimal import Decimal
+
+from kfinance.decimal_with_unit import Money, Shares
+from kfinance.models.price_models import PriceHistory, Prices
+
+
+class TestPriceHistory:
+    api_resp = {
+        "currency": "USD",
+        "prices": [
+            {
+                "date": "2024-06-25",
+                "open": "445.790000",
+                "high": "449.240000",
+                "low": "442.770000",
+                "close": "448.780000",
+                "volume": "999134",
+            },
+            {
+                "date": "2024-06-26",
+                "open": "446.320000",
+                "high": "449.120000",
+                "low": "443.560000",
+                "close": "448.360000",
+                "volume": "1630769",
+            },
+        ],
+    }
+
+    def test_price_history_deserialization(self) -> None:
+        """
+        GIVEN a price history API response
+        WHEN we deserialize the response into a PriceHistory object
+        THEN the deserialization succeeds and returns the expected value.
+        """
+        expected_price_history = PriceHistory.model_construct(
+            prices=[
+                Prices(
+                    date="2024-06-25",
+                    open=Money(value=Decimal("445.79"), unit="USD", conventional_decimals=2),
+                    high=Money(value=Decimal("449.24"), unit="USD", conventional_decimals=2),
+                    low=Money(value=Decimal("442.77"), unit="USD", conventional_decimals=2),
+                    close=Money(value=Decimal("448.78"), unit="USD", conventional_decimals=2),
+                    volume=Shares(value=Decimal("999134"), unit="Shares", conventional_decimals=0),
+                ),
+                Prices(
+                    date="2024-06-26",
+                    open=Money(value=Decimal("446.32"), unit="USD", conventional_decimals=2),
+                    high=Money(value=Decimal("449.12"), unit="USD", conventional_decimals=2),
+                    low=Money(value=Decimal("443.56"), unit="USD", conventional_decimals=2),
+                    close=Money(value=Decimal("448.36"), unit="USD", conventional_decimals=2),
+                    volume=Shares(value=Decimal("1630769"), unit="Shares", conventional_decimals=0),
+                ),
+            ]
+        )
+
+        price_history = PriceHistory.model_validate(self.api_resp)
+        assert price_history == expected_price_history

kfinance/tests/test_objects.py

@@ -10,7 +10,6 @@ import pandas as pd
 from PIL.Image import open as image_open
 import time_machine
 
-from kfinance.constants import BusinessRelationshipType
 from kfinance.kfinance import (
     AdvisedCompany,
     BusinessRelationships,
@@ -22,6 +21,8 @@ from kfinance.kfinance import (
     TradingItem,
     Transcript,
 )
+from kfinance.models.business_relationship_models import BusinessRelationshipType
+from kfinance.models.capitalization_models import Capitalizations
 from kfinance.pydantic_models import CompanyIdAndName, RelationshipResponse
 
 
@@ -329,23 +330,26 @@ class MockKFinanceApiClient:
         company_id: int,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-    ) -> dict:
-        return {
-            "market_caps": [
-                {
-                    "date": "2025-01-01",
-                    "market_cap": "3133802247084.000000",
-                    "tev": "3152211247084.000000",
-                    "shares_outstanding": 7434880776,
-                },
-                {
-                    "date": "2025-01-02",
-                    "market_cap": "3112092395218.000000",
-                    "tev": "3130501395218.000000",
-                    "shares_outstanding": 7434880776,
-                },
-            ]
-        }
+    ) -> Capitalizations:
+        return Capitalizations.model_validate(
+            {
+                "currency": "USD",
+                "market_caps": [
+                    {
+                        "date": "2025-01-01",
+                        "market_cap": "3133802247084.000000",
+                        "tev": "3152211247084.000000",
+                        "shares_outstanding": 7434880776,
+                    },
+                    {
+                        "date": "2025-01-02",
+                        "market_cap": "3112092395218.000000",
+                        "tev": "3130501395218.000000",
+                        "shares_outstanding": 7434880776,
+                    },
+                ],
+            }
+        )
 
     def fetch_segments(
         self,
@@ -843,12 +847,14 @@ class TestTicker(TestCase):
         THEN the Ticker object can correctly extract market caps from the dict.
         """
 
-        expected_dataframe = pd.DataFrame(
-            {"market_cap": {"2025-01-01": 3133802247084.0, "2025-01-02": 3112092395218.0}}
-        )
-        expected_dataframe.index.name = "date"
+        expected_response = {
+            "market_cap": [
+                {"2025-01-01": {"unit": "USD", "value": "3133802247084.00"}},
+                {"2025-01-02": {"unit": "USD", "value": "3112092395218.00"}},
+            ]
+        }
         market_caps = self.msft_ticker_from_ticker.market_cap()
-        pd.testing.assert_frame_equal(expected_dataframe, market_caps)
+        assert market_caps == expected_response
 
 
 class TestTranscript(TestCase):