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

kfinance/{constants.py → models/line_item_models.py}

@@ -1,8 +1,5 @@
-from datetime import date
 from itertools import chain
-from typing import NamedTuple, TypedDict
-
-from strenum import StrEnum
+from typing import TypedDict
 
 
 class LineItemType(TypedDict):
@@ -12,150 +9,6 @@ class LineItemType(TypedDict):
     spgi_name: str
 
 
-class HistoryMetadata(TypedDict):
-    currency: str
-    symbol: str
-    exchange_name: str
-    instrument_type: str
-    first_trade_date: date
-
-
-class IdentificationTriple(NamedTuple):
-    trading_item_id: int
-    security_id: int
-    company_id: int
-
-
-class Capitalization(StrEnum):
-    """The capitalization type"""
-
-    market_cap = "market_cap"
-    tev = "tev"
-    shares_outstanding = "shares_outstanding"
-
-
-class PeriodType(StrEnum):
-    """The period type"""
-
-    annual = "annual"
-    quarterly = "quarterly"
-    ltm = "ltm"
-    ytd = "ytd"
-
-
-class Periodicity(StrEnum):
-    """The frequency or interval at which the historical data points are sampled or aggregated. Periodicity is not the same as the date range. The date range specifies the time span over which the data is retrieved, while periodicity determines how the data within that date range is aggregated."""
-
-    day = "day"
-    week = "week"
-    month = "month"
-    year = "year"
-
-
-class StatementType(StrEnum):
-    """The type of financial statement"""
-
-    balance_sheet = "balance_sheet"
-    income_statement = "income_statement"
-    cashflow = "cashflow"
-
-
-class SegmentType(StrEnum):
-    """The type of segment"""
-
-    business = "business"
-    geographic = "geographic"
-
-
-class BusinessRelationshipType(StrEnum):
-    """The type of business relationship"""
-
-    supplier = "supplier"
-    customer = "customer"
-    distributor = "distributor"
-    franchisor = "franchisor"
-    franchisee = "franchisee"
-    landlord = "landlord"
-    tenant = "tenant"
-    licensor = "licensor"
-    licensee = "licensee"
-    creditor = "creditor"
-    borrower = "borrower"
-    lessor = "lessor"
-    lessee = "lessee"
-    strategic_alliance = "strategic_alliance"
-    investor_relations_firm = "investor_relations_firm"
-    investor_relations_client = "investor_relations_client"
-    transfer_agent = "transfer_agent"
-    transfer_agent_client = "transfer_agent_client"
-    vendor = "vendor"
-    client_services = "client_services"
-
-
-class Permission(StrEnum):
-    EarningsPermission = "EarningsPermission"
-    TranscriptsPermission = "TranscriptsPermission"
-    GICSPermission = "GICSPermission"
-    IDPermission = "IDPermission"
-    ISCRSPermission = "ISCRSPermission"
-    PricingPermission = "PricingPermission"
-    RelationshipPermission = "RelationshipPermission"
-    StatementsPermission = "StatementsPermission"
-    SegmentsPermission = "SegmentsPermission"
-    MergersPermission = "MergersPermission"
-    CompetitorsPermission = "CompetitorsPermission"
-
-
-class CompetitorSource(StrEnum):
-    """The source type of the competitor information: 'filing' (from SEC filings), 'key_dev' (from key developments), 'contact' (from contact relationships), 'third_party' (from third-party sources), 'self_identified' (self-identified), 'named_by_competitor' (from competitor's perspective)."""
-
-    all = "all"
-    filing = "filing"
-    key_dev = "key_dev"
-    contact = "contact"
-    third_party = "third_party"
-    self_identified = "self_identified"
-    named_by_competitor = "named_by_competitor"
-
-
-class YearAndQuarter(TypedDict):
-    year: int
-    quarter: int
-
-
-class LatestAnnualPeriod(TypedDict):
-    latest_year: int
-
-
-class LatestQuarterlyPeriod(TypedDict):
-    latest_quarter: int
-    latest_year: int
-
-
-class CurrentPeriod(TypedDict):
-    current_year: int
-    current_quarter: int
-    current_month: int
-    current_date: str
-
-
-class LatestPeriods(TypedDict):
-    annual: LatestAnnualPeriod
-    quarterly: LatestQuarterlyPeriod
-    now: CurrentPeriod
-
-
-class IndustryClassification(StrEnum):
-    sic = "sic"
-    naics = "naics"
-    nace = "nace"
-    anzsic = "anzsic"
-    spcapiqetf = "spcapiqetf"
-    spratings = "spratings"
-    gics = "gics"
-    simple = "simple"
-
-
 # all of these values must be lower case keys
 LINE_ITEMS: list[LineItemType] = [
     {
@@ -1740,23 +1593,6 @@ LINE_ITEMS: list[LineItemType] = [
         "spgi_name": "Total Debt/Equity",
     },
 ]
-
-
 LINE_ITEM_NAMES_AND_ALIASES: list[str] = list(
     chain(*[[line_item["name"]] + list(line_item["aliases"]) for line_item in LINE_ITEMS])
 )
-
-
-FINANCIAL_STATEMENTS: dict[str, int] = {
-    "income_statement": 1,
-    "balance_sheet": 2,
-    "cash_flow": 3,
-}
-
-FINANCIAL_STATEMENTS_SYNONYMS: dict[str, int] = {
-    "is": 1,
-    "bs": 2,
-    "cf": 3,
-    "income_stmt": 1,
-    "cashflow": 3,
-}

kfinance/models/permission_models.py

@@ -0,0 +1,15 @@
+from strenum import StrEnum
+
+
+class Permission(StrEnum):
+    CompetitorsPermission = "CompetitorsPermission"
+    EarningsPermission = "EarningsPermission"
+    GICSPermission = "GICSPermission"
+    IDPermission = "IDPermission"
+    ISCRSPermission = "ISCRSPermission"
+    MergersPermission = "MergersPermission"
+    PricingPermission = "PricingPermission"
+    RelationshipPermission = "RelationshipPermission"
+    SegmentsPermission = "SegmentsPermission"
+    StatementsPermission = "StatementsPermission"
+    TranscriptsPermission = "TranscriptsPermission"

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