kensho-kfinance 2.0.0__tar.gz → 2.1.2__tar.gz

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/.readthedocs.yaml

@@ -3,13 +3,15 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
-    # You can also specify other tool versions:
-    # nodejs: "16"
-  # borrowed from here:
-  # https://docs.readthedocs.com/platform/stable/build-customization.html#avoid-having-a-dirty-git-index
   jobs:
     pre_install:
+      # borrowed from here:
+      # https://docs.readthedocs.com/platform/stable/build-customization.html#avoid-having-a-dirty-git-index
       - git update-index --assume-unchanged docs/conf.py
+    pre_build:
+      # build documentation for tool calling before generating docs.
+      - pip install langchain-core
+      - python docs/build_tool_calling_documentation.py
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

{kensho_kfinance-2.0.0/kensho_kfinance.egg-info → kensho_kfinance-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.0.0
+Version: 2.1.2
 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
@@ -12,6 +12,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.md
+Requires-Dist: cachetools<6,>=5.5
 Requires-Dist: langchain-core>=0.3.15
 Requires-Dist: langchain-google-genai<3,>=2.1.0
 Requires-Dist: numpy>=1.22.4
@@ -33,6 +34,7 @@ Requires-Dist: pytest-cov<7,>=6.0.0; extra == "dev"
 Requires-Dist: requests_mock<2,>=1.12; extra == "dev"
 Requires-Dist: ruff<1,>=0.9.4; extra == "dev"
 Requires-Dist: time_machine<3,>=2.1; extra == "dev"
+Requires-Dist: types-cachetools<6,>=5.5; extra == "dev"
 Dynamic: license-file
 
 # kFinance

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/docs/build_tool_calling_documentation.py

@@ -1,5 +1,5 @@
-import inspect
 from enum import Enum
+import inspect
 from pathlib import Path
 
 from langchain_core.utils.function_calling import convert_to_openai_tool
@@ -48,11 +48,7 @@ def add_function_to_tools_file(tool: KfinanceTool) -> None:
     """
 
     # The signature built with the inspect module does not include necessary imports.
-    imports = [
-        "import kfinance",
-        "import datetime",
-        "from typing import Optional"
-    ]
+    imports = ["import kfinance", "import datetime", "from typing import Optional"]
     signature_str = build_signature_str(tool)
 
     # Use inspect to retrieve the return type and add it to the imports if it's not a builtin.
@@ -66,10 +62,6 @@ def add_function_to_tools_file(tool: KfinanceTool) -> None:
     for field_name, field_metadata in tool.args_schema.model_fields.items():
         # We use the openai definition to extract the field description. This means that, just like
         # pydantic/langchain, we use the docstring of an enum as the description for an enum field.
-        try:
-            openai_params[field_name]['description']
-        except:
-            assert False, tool.name
         args += f"\n    :param {field_name}: {openai_params[field_name]['description']}"
         args += f"\n    :type {field_name}: {display_as_type(field_metadata.annotation)}"
 
@@ -84,7 +76,8 @@ def add_function_to_tools_file(tool: KfinanceTool) -> None:
     with open(inspect.getfile(tool.__class__), mode="a") as f:
         f.write(func_str)
 
-def build_signature_str(tool) -> str:
+
+def build_signature_str(tool: KfinanceTool) -> str:
     """Return the signature string of the tool
 
     Return value example:
@@ -104,7 +97,6 @@ def build_signature_str(tool) -> str:
     return f"def {tool.name}{signature}:"
 
 
-
 def add_module_to_tool_calling_rst(tool: KfinanceTool) -> None:
     """Add a module for each tool to tool_calling.rst.
 
@@ -121,3 +113,6 @@ def add_module_to_tool_calling_rst(tool: KfinanceTool) -> None:
 
     with open(Path(Path(__file__).resolve().parent, "tool_calling.rst"), mode="a") as f:
         f.write(module_str)
+
+if __name__ == "__main__":
+    add_tool_calling_docs_for_all_tools()

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/docs/conf.py

@@ -7,15 +7,10 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 from importlib.metadata import version as get_version
 
-from docs.build_tool_calling_documentation import add_tool_calling_docs_for_all_tools
-
-
 project = "kensho-kfinance"
 copyright = "2025, Kensho Technologies"
 author = "Kensho Technologies"
 
-# Add documentation for tool calling.
-add_tool_calling_docs_for_all_tools()
 
 # borrowed from here:
 # https://setuptools-scm.readthedocs.io/en/latest/usage/#usage-from-sphinx
@@ -59,7 +54,6 @@ templates_path = ["templates"]
 source_suffix = [".rst", ".md"]
 
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2/kensho_kfinance.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.0.0
+Version: 2.1.2
 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
@@ -12,6 +12,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.md
+Requires-Dist: cachetools<6,>=5.5
 Requires-Dist: langchain-core>=0.3.15
 Requires-Dist: langchain-google-genai<3,>=2.1.0
 Requires-Dist: numpy>=1.22.4
@@ -33,6 +34,7 @@ Requires-Dist: pytest-cov<7,>=6.0.0; extra == "dev"
 Requires-Dist: requests_mock<2,>=1.12; extra == "dev"
 Requires-Dist: ruff<1,>=0.9.4; extra == "dev"
 Requires-Dist: time_machine<3,>=2.1; extra == "dev"
+Requires-Dist: types-cachetools<6,>=5.5; extra == "dev"
 Dynamic: license-file
 
 # kFinance

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/kensho_kfinance.egg-info/SOURCES.txt

@@ -37,8 +37,11 @@ kfinance/py.typed
 kfinance/server_thread.py
 kfinance/version.py
 kfinance/tests/__init__.py
+kfinance/tests/conftest.py
 kfinance/tests/test_batch_requests.py
+kfinance/tests/test_client.py
 kfinance/tests/test_fetch.py
+kfinance/tests/test_group_objects.py
 kfinance/tests/test_objects.py
 kfinance/tests/test_tools.py
 kfinance/tool_calling/README.md

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/kensho_kfinance.egg-info/requires.txt

@@ -1,3 +1,4 @@
+cachetools<6,>=5.5
 langchain-core>=0.3.15
 langchain-google-genai<3,>=2.1.0
 numpy>=1.22.4
@@ -20,3 +21,4 @@ pytest-cov<7,>=6.0.0
 requests_mock<2,>=1.12
 ruff<1,>=0.9.4
 time_machine<3,>=2.1
+types-cachetools<6,>=5.5

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/kfinance/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v2.1.2
+- Allow batch executor to handle multiple requests
+
+## v2.1.1
+- Use cachetools cache
+
+## v2.1.0
+- Filter llm tools by user permissions
+
+## v2.0.2
+- Add Client.tickers() method for ticker industry filters for ISRCS and GICS
+
+## v2.0.1
+- Fix readthedocs integration for llm tools.
+
 ## v2.0.0
 - Refactor llm tools to use langchain `BaseTool`.
 

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/kfinance/batch_request_handling.py

@@ -72,19 +72,19 @@ def add_methods_of_singular_class_to_iterable_class(singular_cls: Type[T]) -> Ca
         def process_in_batch(
             method: Callable, self: IterableKfinanceClass, *args: Any, **kwargs: Any
         ) -> dict:
-            results = {}
             kfinance_api_client = self.kfinance_api_client
             with kfinance_api_client.batch_request_header(batch_size=len(self)):
-                with kfinance_api_client.thread_pool as executor:
-                    results = dict(
-                        zip(
-                            self,
-                            [
-                                process_in_thread_pool(executor, method, obj, *args, **kwargs)
-                                for obj in self
-                            ],
-                        )
+                results = dict(
+                    zip(
+                        self,
+                        [
+                            process_in_thread_pool(
+                                kfinance_api_client.thread_pool, method, obj, *args, **kwargs
+                            )
+                            for obj in self
+                        ],
                     )
+                )
 
             return results
 

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/kfinance/constants.py

@@ -1,7 +1,6 @@
 from datetime import date
-from enum import Enum
 from itertools import chain
-from typing import TypedDict
+from typing import NamedTuple, TypedDict
 
 from strenum import StrEnum
 
@@ -21,13 +20,13 @@ class HistoryMetadata(TypedDict):
     first_trade_date: date
 
 
-class IdentificationTriple(TypedDict):
+class IdentificationTriple(NamedTuple):
     trading_item_id: int
     security_id: int
     company_id: int
 
 
-class Capitalization(Enum):
+class Capitalization(StrEnum):
     """The capitalization type"""
 
     market_cap = "market_cap"
@@ -35,7 +34,7 @@ class Capitalization(Enum):
     shares_outstanding = "shares_outstanding"
 
 
-class PeriodType(Enum):
+class PeriodType(StrEnum):
     """The period type"""
 
     annual = "annual"
@@ -44,7 +43,7 @@ class PeriodType(Enum):
     ytd = "ytd"
 
 
-class Periodicity(Enum):
+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"
@@ -53,7 +52,7 @@ class Periodicity(Enum):
     year = "year"
 
 
-class StatementType(Enum):
+class StatementType(StrEnum):
     """The type of financial statement"""
 
     balance_sheet = "balance_sheet"
@@ -88,6 +87,16 @@ class BusinessRelationshipType(StrEnum):
     client_services = "client_services"
 
 
+class Permission(StrEnum):
+    EarningsPermission = "EarningsPermission"
+    GICSPermission = "GICSPermission"
+    IDPermission = "IDPermission"
+    ISCRSPermission = "ISCRSPermission"
+    PricingPermission = "PricingPermission"
+    RelationshipPermission = "RelationshipPermission"
+    StatementsPermission = "StatementsPermission"
+
+
 class YearAndQuarter(TypedDict):
     year: int
     quarter: int

{kensho_kfinance-2.0.0 → kensho_kfinance-2.1.2}/kfinance/fetch.py

@@ -1,5 +1,6 @@
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager
+import logging
 from time import time
 from typing import Callable, Generator, Optional
 from uuid import uuid4
@@ -13,6 +14,7 @@ from .constants import (
     IndustryClassification,
     Periodicity,
     PeriodType,
+    Permission,
 )
 
 
@@ -23,6 +25,8 @@ try:
 except ImportError:
     kfinance_version = "dev"
 
+logger = logging.getLogger(__name__)
+
 
 DEFAULT_API_HOST: str = "https://kfinance.kensho.com"
 DEFAULT_API_VERSION: int = 1
@@ -86,6 +90,7 @@ class KFinanceApiClient:
         self.user_agent_source = "object_oriented"
         self._batch_id: str | None = None
         self._batch_size: str | None = None
+        self._user_permissions: set[Permission] | None = None
 
     @contextmanager
     def batch_request_header(self, batch_size: int) -> Generator:
@@ -127,6 +132,9 @@ class KFinanceApiClient:
                 # nosemgrep:  python.jwt.security.unverified-jwt-decode.unverified-jwt-decode
                 options={"verify_signature": False},
             ).get("exp")
+            # When the access token gets refreshed, also refresh user permissions in case they
+            # have been updated.
+            self._refresh_user_permissions()
         return self._access_token
 
     def _get_access_token_via_refresh_token(self) -> str:
@@ -169,6 +177,33 @@ class KFinanceApiClient:
         response.raise_for_status()
         return response.json().get("access_token")
 
+    @property
+    def user_permissions(self) -> set[Permission]:
+        """Return the permissions that the current user holds."""
+
+        if self._user_permissions is None:
+            self._refresh_user_permissions()
+            # _refresh_user_permissions updates self._user_permissions in place
+            assert self._user_permissions is not None
+        return self._user_permissions
+
+    def _refresh_user_permissions(self) -> None:
+        """Fetches user permissions and stores them as KfinanceApiClient._user_permissions."""
+
+        user_permission_dict = self.fetch_permissions()
+        self._user_permissions = set()
+        for permission_str in user_permission_dict["permissions"]:
+            try:
+                self._user_permissions.add(Permission[permission_str])
+            except KeyError:
+                logger.warning(
+                    "Could not resolve %s to a member of the Permission enum. "
+                    "%s may be a new type of permission that still needs to be "
+                    "added to the enum.",
+                    permission_str,
+                    permission_str,
+                )
+
     def fetch(self, url: str) -> dict:
         """Does the request and auth"""
 
@@ -191,6 +226,11 @@ class KFinanceApiClient:
         response.raise_for_status()
         return response.json()
 
+    def fetch_permissions(self) -> dict[str, list[str]]:
+        """Return the permissions of the user."""
+        url = f"{self.url_base}users/permissions"
+        return self.fetch(url)
+
     def fetch_id_triple(self, identifier: str, exchange_code: Optional[str] = None) -> dict:
         """Get the ID triple from [identifier]."""
         url = f"{self.url_base}id/{identifier}"
@@ -241,7 +281,7 @@ class KFinanceApiClient:
             f"{self.url_base}pricing/{trading_item_id}/"
             f"{start_date if start_date is not None else 'none'}/"
             f"{end_date if end_date is not None else 'none'}/"
-            f"{periodicity.value if periodicity else 'none'}/"
+            f"{periodicity if periodicity else 'none'}/"
             f"{'adjusted' if is_adjusted else 'unadjusted'}"
         )
         return self.fetch(url)
@@ -278,7 +318,7 @@ class KFinanceApiClient:
             f"{self.url_base}price_chart/{trading_item_id}/"
             f"{start_date if start_date is not None else 'none'}/"
             f"{end_date if end_date is not None else 'none'}/"
-            f"{periodicity.value if periodicity else 'none'}/"
+            f"{periodicity if periodicity else 'none'}/"
             f"{'adjusted' if is_adjusted else 'unadjusted'}"
         )
 
@@ -306,7 +346,7 @@ class KFinanceApiClient:
         """Get a specified financial statement for a specified duration."""
         url = (
             f"{self.url_base}statements/{company_id}/{statement_type}/"
-            f"{period_type.value if period_type else 'none'}/"
+            f"{period_type if period_type else 'none'}/"
             f"{start_year if start_year is not None else 'none'}/"
             f"{end_year if end_year is not None else 'none'}/"
             f"{start_quarter if start_quarter is not None else 'none'}/"
@@ -327,7 +367,7 @@ class KFinanceApiClient:
         """Get a specified financial line item for a specified duration."""
         url = (
             f"{self.url_base}line_item/{company_id}/{line_item}/"
-            f"{period_type.value if period_type else 'none'}/"
+            f"{period_type if period_type else 'none'}/"
             f"{start_year if start_year is not None else 'none'}/"
             f"{end_year if end_year is not None else 'none'}/"
             f"{start_quarter if start_quarter is not None else 'none'}/"
@@ -358,10 +398,12 @@ class KFinanceApiClient:
         self,
         country_iso_code: str,
         state_iso_code: Optional[str] = None,
-    ) -> dict[str, list[IdentificationTriple]]:
+    ) -> list[IdentificationTriple]:
         """Fetch ticker geography groups"""
-        return self.fetch_geography_groups(
-            country_iso_code=country_iso_code, state_iso_code=state_iso_code, fetch_ticker=True
+        return self._tickers_response_to_id_triple(
+            self.fetch_geography_groups(
+                country_iso_code=country_iso_code, state_iso_code=state_iso_code, fetch_ticker=True
+            )
         )
 
     def fetch_company_geography_groups(
@@ -381,13 +423,13 @@ class KFinanceApiClient:
         url = f"{self.url_base}{'ticker_groups' if fetch_ticker else 'trading_item_groups'}/exchange/{exchange_code}"
         return self.fetch(url)
 
-    def fetch_ticker_exchange_groups(
-        self, exchange_code: str
-    ) -> dict[str, list[IdentificationTriple]]:
+    def fetch_ticker_exchange_groups(self, exchange_code: str) -> list[IdentificationTriple]:
         """Fetch ticker exchange groups"""
-        return self.fetch_exchange_groups(
-            exchange_code=exchange_code,
-            fetch_ticker=True,
+        return self._tickers_response_to_id_triple(
+            self.fetch_exchange_groups(
+                exchange_code=exchange_code,
+                fetch_ticker=True,
+            )
         )
 
     def fetch_trading_item_exchange_groups(self, exchange_code: str) -> dict[str, list[int]]:
@@ -397,13 +439,32 @@ class KFinanceApiClient:
             fetch_ticker=False,
         )
 
+    @staticmethod
+    def _tickers_response_to_id_triple(
+        tickers_response: dict[str, list[dict]],
+    ) -> list[IdentificationTriple]:
+        """For fetch ticker cases with a dict[str, list[dict]] response, return a list[IdentificationTriple].
+
+        For example, with a given fetch tickers response:
+        {"tickers" : [{"trading_item_id": 1, "security_id": 1, "company_id": 1}, {"trading_item_id": 2,"security_id": 2,"company_id": 2}]},
+        return [[1, 1, 1], [2, 2, 2]].
+        """
+        return [
+            IdentificationTriple(
+                trading_item_id=ticker["trading_item_id"],
+                security_id=ticker["security_id"],
+                company_id=ticker["company_id"],
+            )
+            for ticker in tickers_response["tickers"]
+        ]
+
     def fetch_ticker_combined(
         self,
         country_iso_code: Optional[str] = None,
         state_iso_code: Optional[str] = None,
         simple_industry: Optional[str] = None,
         exchange_code: Optional[str] = None,
-    ) -> dict[str, list[IdentificationTriple]]:
+    ) -> list[IdentificationTriple]:
         """Fetch tickers using combined filters route"""
         if (
             country_iso_code is None
@@ -414,11 +475,11 @@ class KFinanceApiClient:
             raise RuntimeError("Invalid parameters: No parameters provided or all set to none")
         elif country_iso_code is None and state_iso_code is not None:
             raise RuntimeError(
-                "Invalid parameters: state_iso_code must be provided with a country_iso_code value"
+                "Invalid parameters: country_iso_code must be provided with a state_iso_code value"
             )
         else:
             url = f"{self.url_base}ticker_groups/filters/geo/{str(country_iso_code).lower()}/{str(state_iso_code).lower()}/simple/{str(simple_industry).lower()}/exchange/{str(exchange_code).lower()}"
-            return self.fetch(url)
+            return self._tickers_response_to_id_triple(self.fetch(url))
 
     def fetch_companies_from_business_relationship(
         self, company_id: int, relationship_type: BusinessRelationshipType
@@ -443,22 +504,11 @@ class KFinanceApiClient:
         url = f"{self.url_base}relationship/{company_id}/{relationship_type}"
         return self.fetch(url)
 
-    def fetch_from_industry_code(
-        self,
-        industry_code: str,
-        industry_classification: IndustryClassification,
-        fetch_ticker: bool = True,
-    ) -> dict[str, list]:
-        """Fetches a list of companies or identification triples that are classified in the given industry_code and industry_classification."""
-
-        url = f"{self.url_base}{'ticker_groups' if fetch_ticker else 'company_groups'}/industry/{industry_classification}/{industry_code}"
-        return self.fetch(url)
-
     def fetch_ticker_from_industry_code(
         self,
         industry_code: str,
         industry_classification: IndustryClassification,
-    ) -> dict[str, list[IdentificationTriple]]:
+    ) -> list[IdentificationTriple]:
         """Fetches a list of identification triples that are classified in the given industry_code and industry_classification.
 
         Returns a dictionary of shape {"tickers": List[{“company_id”: <company_id>, “security_id”: <security_id>, “trading_item_id”: <trading_item_id>}]}.
@@ -466,14 +516,11 @@ class KFinanceApiClient:
         :type industry_code: str
         :param industry_classification: The type of industry_classification to filter on.
         :type industry_classification: IndustryClassification
-        :return: A dictionary containing the list of identification triple [company_id, security_id, trading_item_id] that are classified in the given industry_code and industry_classification.
-        :rtype: dict[str, list[IdentificationTriple]]
+        :return: A list of identification triples [company_id, security_id, trading_item_id] that are classified in the given industry_code and industry_classification.
+        :rtype: list[IdentificationTriple]
         """
-        return self.fetch_from_industry_code(
-            industry_code=industry_code,
-            industry_classification=industry_classification,
-            fetch_ticker=True,
-        )
+        url = f"{self.url_base}ticker_groups/industry/{industry_classification}/{industry_code}"
+        return self._tickers_response_to_id_triple(self.fetch(url))
 
     def fetch_company_from_industry_code(
         self,
@@ -490,8 +537,5 @@ class KFinanceApiClient:
         :return: A dictionary containing the list of companies that are classified in the given industry_code and industry_classification.
         :rtype: dict[str, list[int]]
         """
-        return self.fetch_from_industry_code(
-            industry_code=industry_code,
-            industry_classification=industry_classification,
-            fetch_ticker=False,
-        )
+        url = f"{self.url_base}company_groups/industry/{industry_classification}/{industry_code}"
+        return self.fetch(url)