kensho-kfinance 1.0.3__tar.gz → 1.1.0__tar.gz

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/.gitignore

@@ -98,3 +98,5 @@ dmypy.json
 .idea/*
 .vscode/
 
+
+kfinance/version.py

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 1.0.3
+Version: 1.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
@@ -28,6 +28,7 @@ Requires-Dist: mypy<2,>=1.15.0; extra == "dev"
 Requires-Dist: pytest<7,>=6.1.2; extra == "dev"
 Requires-Dist: pytest-cov<7,>=6.0.0; extra == "dev"
 Requires-Dist: ruff<1,>=0.9.4; extra == "dev"
+Dynamic: license-file
 
 # kFinance
 
@@ -39,7 +40,7 @@ Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-
 
 # Setup
 
-You can install kFinance on [PyPI](https://pypi.org/project/kfinance/) via 
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via 
 
 `pip install kensho-kfinance`
 
@@ -49,6 +50,11 @@ To receive access, please email [S&P Global Market Intelligence](market.intellig
 
 Once access is obtained, get started using the [Authentication Guide](https://docs.kensho.com/llmreadyapi/kf-authentication) and [Usage Guide](https://docs.kensho.com/llmreadyapi/usage).
 
+# Versioning
+The kFinance uses semantic versioning (major, minor, patch). 
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 
+This will generate a new version of the library as part of the release process.
+
 # License
 
 Use is solely in accordance with the signed agreement between your entity and S&P.

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/README.md

@@ -8,7 +8,7 @@ Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-
 
 # Setup
 
-You can install kFinance on [PyPI](https://pypi.org/project/kfinance/) via 
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via 
 
 `pip install kensho-kfinance`
 
@@ -18,6 +18,11 @@ To receive access, please email [S&P Global Market Intelligence](market.intellig
 
 Once access is obtained, get started using the [Authentication Guide](https://docs.kensho.com/llmreadyapi/kf-authentication) and [Usage Guide](https://docs.kensho.com/llmreadyapi/usage).
 
+# Versioning
+The kFinance uses semantic versioning (major, minor, patch). 
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 
+This will generate a new version of the library as part of the release process.
+
 # License
 
 Use is solely in accordance with the signed agreement between your entity and S&P.

kensho_kfinance-1.1.0/justfile

@@ -0,0 +1,31 @@
+set dotenv-load
+
+# Just is a command runner. It can be used to provide a shorthand to run
+# complex commands, for example `just lint` for `python -m kensho_lint.lint...`
+
+# Here are some installation instructions:
+# https://github.com/casey/just?tab=readme-ov-file#installation
+# Once installed, you can run any of the commands in this file by
+# prepending them with `just`, for example `just lint` to run the linter.
+# Run `just` shows a list of all available commands
+
+# If there are commands that you believe can be useful to other contributors,
+# feel free to add them.
+
+
+default:
+    just --list
+
+alias l := lint
+# Lint the app directory (both lint and l work). For verbose, use `just lint --verbose`
+lint *args:
+    python -m mypy --config-file pyproject.toml kfinance {{args}}
+    # The ruff linters (check) and formatters (format) are separate.
+    # See https://docs.astral.sh/ruff/formatter/#sorting-imports
+    python -m ruff --config pyproject.toml check kfinance --fix {{args}}
+    python -m ruff --config pyproject.toml format kfinance {{args}}
+
+alias t := unit-test
+# Run unit tests. Use args for optional settings
+unit-test *args:
+    python -m pytest {{args}}

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kensho_kfinance.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 1.0.3
+Version: 1.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
@@ -28,6 +28,7 @@ Requires-Dist: mypy<2,>=1.15.0; extra == "dev"
 Requires-Dist: pytest<7,>=6.1.2; extra == "dev"
 Requires-Dist: pytest-cov<7,>=6.0.0; extra == "dev"
 Requires-Dist: ruff<1,>=0.9.4; extra == "dev"
+Dynamic: license-file
 
 # kFinance
 
@@ -39,7 +40,7 @@ Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-
 
 # Setup
 
-You can install kFinance on [PyPI](https://pypi.org/project/kfinance/) via 
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via 
 
 `pip install kensho-kfinance`
 
@@ -49,6 +50,11 @@ To receive access, please email [S&P Global Market Intelligence](market.intellig
 
 Once access is obtained, get started using the [Authentication Guide](https://docs.kensho.com/llmreadyapi/kf-authentication) and [Usage Guide](https://docs.kensho.com/llmreadyapi/usage).
 
+# Versioning
+The kFinance uses semantic versioning (major, minor, patch). 
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 
+This will generate a new version of the library as part of the release process.
+
 # License
 
 Use is solely in accordance with the signed agreement between your entity and S&P.

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kensho_kfinance.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ CODE_OF_CONDUCT.md
 CONTRIBUTING.md
 LICENSE
 README.md
+justfile
 pyproject.toml
 setup.py
 .github/workflows/ci-lint.yml

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kfinance/CHANGELOG.md

@@ -1,4 +1,7 @@
 # Changelog
+## v1.1.0
+- Add market cap, TEV, and shares outstanding
+
 ## v1.0.3
 - Fix typo for get_history_metadata_from_identifier.
 

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kfinance/fetch.py

@@ -5,7 +5,14 @@ import jwt
 import requests
 
 from .constants import BusinessRelationshipType, IdentificationTriple
-from .version import __version__ as kfinance_version
+
+
+# version.py gets autogenerated by setuptools-scm and is not available
+# during local development.
+try:
+    from .version import __version__ as kfinance_version
+except ImportError:
+    kfinance_version = "dev"
 
 
 DEFAULT_API_HOST: str = "https://kfinance.kensho.com"
@@ -175,6 +182,20 @@ class KFinanceApiClient:
         url = f"{self.url_base}pricing/{trading_item_id}/metadata"
         return self.fetch(url)
 
+    def fetch_market_caps_tevs_and_shares_outstanding(
+        self,
+        company_id: int,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> dict:
+        """Get the market cap, TEV, and shares outstanding for a company."""
+        url = (
+            f"{self.url_base}market_cap/{company_id}/"
+            f"{start_date if start_date is not None else 'none'}/"
+            f"{end_date if end_date is not None else 'none'}"
+        )
+        return self.fetch(url)
+
     def fetch_price_chart(
         self,
         trading_item_id: int,

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kfinance/llm_tools.py

@@ -4,7 +4,7 @@ import copy
 import datetime
 from enum import Enum
 from functools import partial
-from typing import TYPE_CHECKING, Callable
+from typing import TYPE_CHECKING, Callable, Literal
 
 from langchain_core.tools import StructuredTool
 
@@ -210,6 +210,31 @@ def get_prices_from_identifier(
     )
 
 
+def get_capitalization_from_identifier(
+    self: Client,
+    identifier: str,
+    capitalization: Literal["market_cap", "tev", "shares_outstanding"],
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> str:
+    """Get the historical market cap, tev (Total Enterprise Value), or shares outstanding of an identifier, where the identifier can be a ticker, ISIN or CUSIP, between inclusive start_date and inclusive end date.
+
+    Args:
+        identifier: A unique identifier, which can be a ticker symbol, ISIN, or CUSIP.
+        capitalization: The capitalization to retrieve (market_cap, tev, or shares_outstanding)
+        start_date: The start date for historical price retrieval in format YYYY-MM-DD
+        end_date: The end date for historical price retrieval in format YYYY-MM-DD
+    """
+    ticker = self.ticker(identifier)
+    capitalization_to_func: dict[Literal["market_cap", "tev", "shares_outstanding"], Callable] = {
+        "market_cap": ticker.market_cap,
+        "tev": ticker.tev,
+        "shares_outstanding": ticker.shares_outstanding,
+    }
+    func = capitalization_to_func[capitalization]
+    return func(start_date=start_date, end_date=end_date).to_markdown()
+
+
 def get_financial_statement_from_identifier(
     self: Client,
     identifier: str,
@@ -297,6 +322,7 @@ def _llm_tools(self: Client) -> dict[str, Callable]:
         ),
         "get_history_metadata_from_identifier": partial(get_history_metadata_from_identifier, self),
         "get_prices_from_identifier": partial(get_prices_from_identifier, self),
+        "get_capitalization_from_identifier": partial(get_capitalization_from_identifier, self),
         "get_financial_statement_from_identifier": partial(
             get_financial_statement_from_identifier, self
         ),
@@ -323,6 +349,7 @@ def _llm_tool_metadata() -> dict:
         "get_earnings_call_datetimes_from_identifier": tool_schemas.GetEarningsCallDatetimesFromIdentifier,
         "get_history_metadata_from_identifier": tool_schemas.GetHistoryMetadataFromIdentifier,
         "get_prices_from_identifier": tool_schemas.GetPricesFromIdentifier,
+        "get_capitalization_from_identifier": tool_schemas.GetCapitalizationFromIdentifier,
         "get_financial_statement_from_identifier": tool_schemas.GetFinancialStatementFromIdentifier,
         "get_financial_line_item_from_identifier": tool_schemas.GetFinancialLineItemFromIdentifier,
         "get_business_relationship_from_identifier": tool_schemas.GetBusinessRelationshipFromIdentifier,
@@ -516,6 +543,34 @@ _base_tool_descriptions = [
             "additionalProperties": False,
         },
     },
+    {
+        "name": "get_capitalization_from_identifier",
+        "description": "Get the historical market cap, tev (Total Enterprise Value), or shares outstanding of an identifier, where the identifier can be a ticker, ISIN or CUSIP, between inclusive start_date and inclusive end date.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "identifier": {
+                    "type": "string",
+                    "description": "A unique identifier, which can be a ticker symbol, ISIN, or CUSIP.",
+                },
+                "capitalization": {
+                    "type": "string",
+                    "description": "The capitalization to retrieve (market_cap, tev, or shares_outstanding).",
+                    "enum": ["market_cap", "tev", "shares_outstanding"],
+                },
+                "start_date": {
+                    "type": "string",
+                    "description": "The start date for historical price retrieval in format YYYY-MM-DD",
+                },
+                "end_date": {
+                    "type": "string",
+                    "description": "The end date for historical price retrieval in format YYYY-MM-DD",
+                },
+            },
+            "required": ["identifier", "capitalization"],
+            "additionalProperties": False,
+        },
+    },
     {
         "name": "get_financial_statement_from_identifier",
         "description": "Get the financial statement associated with an identifier",

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kfinance/meta_classes.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from functools import cache, cached_property
 import logging
-from typing import TYPE_CHECKING, Any, Callable, Optional
+from typing import TYPE_CHECKING, Any, Callable, Literal, Optional
 
 import numpy as np
 import pandas as pd
@@ -18,9 +18,7 @@ logger = logging.getLogger(__name__)
 
 
 class CompanyFunctionsMetaClass:
-    def __init__(self) -> None:
-        """Init company functions"""
-        self.kfinance_api_client: KFinanceApiClient
+    kfinance_api_client: KFinanceApiClient
 
     @cached_property
     def company_id(self) -> Any:
@@ -239,6 +237,78 @@ class CompanyFunctionsMetaClass:
             Companies(self.kfinance_api_client, companies["previous"]),
         )
 
+    def market_cap(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """Retrieves market caps for a company between start and end date.
+
+        :param start_date: The start date in format "YYYY-MM-DD", default to None
+        :type start_date: str, optional
+        :param end_date: The end date in format "YYYY-MM-DD", default to None
+        :type end_date: str, optional
+        :return: A DataFrame with a `market_cap` column. The dates are the index.
+        :rtype: pd.DataFrame
+        """
+
+        return self._fetch_market_cap_tev_or_shares_outstanding(
+            column_to_extract="market_cap", start_date=start_date, end_date=end_date
+        )
+
+    def tev(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """Retrieves TEV (total enterprise value) for a company between start and end date.
+
+        :param start_date: The start date in format "YYYY-MM-DD", default to None
+        :type start_date: str, optional
+        :param end_date: The end date in format "YYYY-MM-DD", default to None
+        :type end_date: str, optional
+        :return: A DataFrame with a `tev` column. The dates are the index.
+        :rtype: pd.DataFrame
+        """
+
+        return self._fetch_market_cap_tev_or_shares_outstanding(
+            column_to_extract="tev", start_date=start_date, end_date=end_date
+        )
+
+    def shares_outstanding(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """Retrieves shares outstanding for a company between start and end date.
+
+        :param start_date: The start date in format "YYYY-MM-DD", default to None
+        :type start_date: str, optional
+        :param end_date: The end date in format "YYYY-MM-DD", default to None
+        :type end_date: str, optional
+        :return: A DataFrame with a `shares_outstanding` column. The dates are the index.
+        :rtype: pd.DataFrame
+        """
+
+        return self._fetch_market_cap_tev_or_shares_outstanding(
+            column_to_extract="shares_outstanding", start_date=start_date, end_date=end_date
+        )
+
+    def _fetch_market_cap_tev_or_shares_outstanding(
+        self,
+        column_to_extract: Literal["market_cap", "tev", "shares_outstanding"],
+        start_date: str | None,
+        end_date: str | None,
+    ) -> pd.DataFrame:
+        """Helper function to fetch market cap, TEV, and shares outstanding."""
+
+        df = pd.DataFrame(
+            self.kfinance_api_client.fetch_market_caps_tevs_and_shares_outstanding(
+                company_id=self.company_id, start_date=start_date, end_date=end_date
+            )["market_caps"]
+        )
+        return df.set_index("date")[[column_to_extract]].apply(pd.to_numeric).replace(np.nan, None)
+
 
 for line_item in LINE_ITEMS:
     line_item_name = line_item["name"]

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kfinance/tests/test_fetch.py

@@ -1,14 +1,22 @@
 from unittest import TestCase
 from unittest.mock import Mock
 
+import pytest
+
 from kfinance.fetch import KFinanceApiClient
 
 
+def build_mock_api_client() -> KFinanceApiClient:
+    """Create a KFinanceApiClient with mocked-out fetch function."""
+    kfinance_api_client = KFinanceApiClient(refresh_token="fake_refresh_token")
+    kfinance_api_client.fetch = Mock()
+    return kfinance_api_client
+
+
 class TestFetchItem(TestCase):
     def setUp(self):
         """Create a KFinanceApiClient with mocked-out fetch function."""
-        self.kfinance_api_client = KFinanceApiClient(refresh_token="fake_refresh_token")
-        self.kfinance_api_client.fetch = Mock()
+        self.kfinance_api_client = build_mock_api_client()
 
     def test_fetch_id_triple(self) -> None:
         identifier = "SPGI"
@@ -239,3 +247,25 @@ class TestFetchItem(TestCase):
             exchange_code=exchange_code,
         )
         self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
+
+
+class TestMarketCap:
+    @pytest.mark.parametrize(
+        "start_date, start_date_url", [(None, "none"), ("2025-01-01", "2025-01-01")]
+    )
+    @pytest.mark.parametrize(
+        "end_date, end_date_url", [(None, "none"), ("2025-01-02", "2025-01-02")]
+    )
+    def test_fetch_market_cap(
+        self, start_date: str | None, start_date_url: str, end_date: str | None, end_date_url: str
+    ) -> None:
+        company_id = 12345
+        client = build_mock_api_client()
+
+        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
+        )
+        client.fetch.assert_called_with(expected_fetch_url)

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kfinance/tests/test_objects.py

@@ -166,6 +166,29 @@ class MockKFinanceApiClient:
         """Get a statement"""
         return MOCK_COMPANY_DB[company_id]["line_items"][line_item]
 
+    def fetch_market_caps_tevs_and_shares_outstanding(
+        self,
+        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,
+                },
+            ]
+        }
+
 
 class TestTradingItem(TestCase):
     def setUp(self):
@@ -549,3 +572,17 @@ class TestTicker(TestCase):
         self.assertEqual(expected_ticker_symbol, self.msft_ticker_from_isin.ticker)
         self.assertEqual(expected_ticker_symbol, self.msft_ticker_from_cusip.ticker)
         self.assertEqual(expected_ticker_symbol, self.msft_ticker_from_id_triple.ticker)
+
+    def test_market_cap(self):
+        """
+        GIVEN a mock client
+        WHEN the mock client receives a mock market cap response dict
+        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"
+        market_caps = self.msft_ticker_from_ticker.market_cap()
+        pd.testing.assert_frame_equal(expected_dataframe, market_caps)

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kfinance/tool_schemas.py

@@ -77,6 +77,20 @@ class GetPricesFromIdentifier(BaseModel):
     )
 
 
+class GetCapitalizationFromIdentifier(BaseModel):
+    identifier: str = Field(
+        description="The identifier, which can be a ticker symbol, ISIN, or CUSIP"
+    )
+    capitalization: Literal["market_cap", "tev", "shares_outstanding"] = Field(
+        description="The capitalization to retrieve"
+    )
+    start_date: str | None = Field(
+        default=None,
+        description="The start date in format YYYY-MM-DD",
+    )
+    end_date: str | None = Field(default=None, description="The end date in format YYYY-MM-DD")
+
+
 class GetFinancialStatementFromIdentifier(BaseModel):
     identifier: str = Field(
         description="The identifier, which can be a ticker symbol, ISIN, or CUSIP"

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.0.3'
-__version_tuple__ = version_tuple = (1, 0, 3)
+__version__ = version = '1.1.0'
+__version_tuple__ = version_tuple = (1, 1, 0)

{kensho_kfinance-1.0.3 → kensho_kfinance-1.1.0}/scripts/lint.sh

@@ -13,7 +13,11 @@ done
 python -m mypy --config-file pyproject.toml kfinance
 
 if [ "$fix" = "--fix" ]; then
+  # The ruff linters (check) and formatters (format) are separate.
+  # See https://docs.astral.sh/ruff/formatter/#sorting-imports
   python -m ruff --config pyproject.toml check kfinance --fix
+  python -m ruff --config pyproject.toml format kfinance
 else
   python -m ruff --config pyproject.toml check kfinance
+  python -m ruff --config pyproject.toml format kfinance --check
 fi