kensho-kfinance 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

{kensho_kfinance-1.1.0.dist-info → kensho_kfinance-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 1.1.0
+Version: 1.2.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"
+Requires-Dist: requests_mock<1.2,>=1.1; extra == "dev"
 Dynamic: license-file
 
 # kFinance

kensho_kfinance-1.2.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+kensho_kfinance-1.2.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-1.2.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=rPeMYaICQiwXrL3vPgLjanjulnxVyovt27dLFqqZ_RA,443
+kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kfinance/batch_request_handling.py,sha256=s0uXRY4CC-GnShI0i8PLPgLddRdqLyQ8jnqDKdmaZzs,5531
+kfinance/constants.py,sha256=SJfI3K2gS0N-M3-rHIMizcxjyTz_iWBc7UYtauUOjDg,47338
+kfinance/fetch.py,sha256=tDPFQQSPMAAnH8gFlT1dgERaHRfQjkW2zcUYcRFbXEY,18130
+kfinance/kfinance.py,sha256=PGJzfq_AdX7IZsY4BpNuni90R6SGa6nrNLicJi_QEec,45643
+kfinance/llm_tools.py,sha256=t3i-5y34AzeFujjwOJVWY7OFI5aOAWG8rt-9KgR_0-E,30683
+kfinance/meta_classes.py,sha256=ryncusGDe48gG31a-Ldx1ApJ-ZPRFJvjC18jry7TOVE,15980
+kfinance/prompt.py,sha256=PtVB8c_FcSlVdyGgByAnIFGzuUuBaEjciCqnBJl1hSQ,25133
+kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
+kfinance/tool_schemas.py,sha256=JrFSbb6i2lOQaI24QqnhGhZ3e-pWLhjNqZloY9WGlnM,5643
+kfinance/version.py,sha256=V2bJXGFUmn_IdFy3HF4zr3V9woAW6i1X0GXwu8-ZCDs,511
+kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kfinance/tests/test_batch_requests.py,sha256=NsldoZqjjQpv0QKM2th80F1nru2tIF4LJeXU-RamQvA,9836
+kfinance/tests/test_fetch.py,sha256=gYSYDSsMUHpwwMODN0_g7kQQAEWq_jsucIRiqhBjAcA,12981
+kfinance/tests/test_objects.py,sha256=egXkhfoK2MepZdXtrBxzWxWni7f-zVCefUbnyDnWDOE,22554
+kensho_kfinance-1.2.0.dist-info/METADATA,sha256=ACI6Utx34JrW1rSNX97cMyDlHq8L_rsQAh7SH9PXWB8,2869
+kensho_kfinance-1.2.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+kensho_kfinance-1.2.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-1.2.0.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,4 +1,7 @@
 # Changelog
+## v1.2.0
+- Add batch requests for iterable classes
+
 ## v1.1.0
 - Add market cap, TEV, and shares outstanding
 

kfinance/batch_request_handling.py

@@ -0,0 +1,137 @@
+from concurrent.futures import ThreadPoolExecutor
+import functools
+from functools import cached_property
+import threading
+from typing import Any, Callable, Iterable, Protocol, Sized, Type, TypeVar
+
+from requests.exceptions import HTTPError
+
+from .fetch import KFinanceApiClient
+
+
+T = TypeVar("T")
+
+MAX_WORKERS_CAP: int = 10
+
+throttle = threading.Semaphore(MAX_WORKERS_CAP)
+
+
+def add_methods_of_singular_class_to_iterable_class(singular_cls: Type[T]) -> Callable:
+    """Returns a decorator that sets each method, property, and cached_property of"""
+    "[singular_cls] as an attribute of the decorated class."
+
+    class IterableKfinanceClass(Protocol, Sized, Iterable[T]):
+        """A protocol to represent a iterable Kfinance classes like Tickers and Companies.
+
+        Each of these classes has a kfinance_api_client attribute.
+        """
+
+        kfinance_api_client: KFinanceApiClient
+
+    def decorator(iterable_cls: Type[IterableKfinanceClass]) -> Type[IterableKfinanceClass]:
+        """Adds functions from a singular class to an iterable class.
+
+        This decorator modifies the [iterable_cls] so that when an attribute
+        (method, property, or cached property) added by the decorator is accessed,
+        it returns a dictionary. This dictionary maps each object in [iterable_cls]
+        to the result of invoking the attribute on that specific object.
+
+        For example, consider a `Company` class with a `city` property and a
+        `Companies` class that is an iterable of `Company` instances. When the
+        `Companies` class is decorated, it gains a `city` property. Accessing this
+        property will yield a dictionary where each key is a `Company` instance
+        and the corresponding value is the city of that instance. The resulting
+        dictionary might look like:
+
+            {<kfinance.kfinance.Company object>: 'Some City'}
+
+        Error Handling:
+            - If the result is a 404 HTTP error, the corresponding value
+            for that object in the dictionary will be set to None.
+            - For any other HTTP error, the error is raised and bubbles up.
+
+        Note:
+            This decorator requires [iterable_cls] to be an iterable of
+            instances of [singular_cls].
+        """
+
+        def process_in_thread_pool(
+            executor: ThreadPoolExecutor, method: Callable, obj: T, *args: Any, **kwargs: Any
+        ) -> Any:
+            with throttle:
+                future = executor.submit(method, obj, *args, **kwargs)
+                try:
+                    return future.result()
+                except HTTPError as http_err:
+                    error_code = http_err.response.status_code
+                    if error_code == 404:
+                        return None
+                    else:
+                        raise http_err
+
+        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
+                            ],
+                        )
+                    )
+
+            return results
+
+        for method_name in dir(singular_cls):
+            method = getattr(singular_cls, method_name)
+            if method_name.startswith("__") or method_name.startswith("set_"):
+                continue
+            if callable(method):
+
+                def create_method_wrapper(method: Callable) -> Callable:
+                    @functools.wraps(method)
+                    def method_wrapper(
+                        self: IterableKfinanceClass, *args: Any, **kwargs: Any
+                    ) -> dict:
+                        return process_in_batch(method, self, *args, **kwargs)
+
+                    return method_wrapper
+
+                setattr(iterable_cls, method_name, create_method_wrapper(method))
+
+            elif isinstance(method, property):
+
+                def create_prop_wrapper(method: property) -> Callable:
+                    assert method.fget is not None
+
+                    @functools.wraps(method.fget)
+                    def prop_wrapper(self: IterableKfinanceClass) -> Any:
+                        assert method.fget is not None
+                        return process_in_batch(method.fget, self)
+
+                    return prop_wrapper
+
+                setattr(iterable_cls, method_name, property(create_prop_wrapper(method)))
+
+            elif isinstance(method, cached_property):
+
+                def create_cached_prop_wrapper(method: cached_property) -> cached_property:
+                    @functools.wraps(method.func)
+                    def cached_prop_wrapper(self: IterableKfinanceClass) -> Any:
+                        return process_in_batch(method.func, self)
+
+                    wrapped_cached_property = cached_property(cached_prop_wrapper)
+                    wrapped_cached_property.__set_name__(iterable_cls, method_name)
+                    return wrapped_cached_property
+
+                setattr(iterable_cls, method_name, create_cached_prop_wrapper(method))
+
+        return iterable_cls
+
+    return decorator

kfinance/fetch.py

@@ -1,5 +1,8 @@
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
 from time import time
-from typing import Callable, Optional
+from typing import Callable, Generator, Optional
+from uuid import uuid4
 
 import jwt
 import requests
@@ -19,6 +22,7 @@ DEFAULT_API_HOST: str = "https://kfinance.kensho.com"
 DEFAULT_API_VERSION: int = 1
 DEFAULT_OKTA_HOST: str = "https://kensho.okta.com"
 DEFAULT_OKTA_AUTH_SERVER: str = "default"
+DEFAULT_MAX_WORKERS: int = 10
 
 
 class KFinanceApiClient:
@@ -27,12 +31,33 @@ class KFinanceApiClient:
         refresh_token: Optional[str] = None,
         client_id: Optional[str] = None,
         private_key: Optional[str] = None,
+        thread_pool: Optional[ThreadPoolExecutor] = None,
         api_host: str = DEFAULT_API_HOST,
         api_version: int = DEFAULT_API_VERSION,
         okta_host: str = DEFAULT_OKTA_HOST,
         okta_auth_server: str = DEFAULT_OKTA_AUTH_SERVER,
     ):
-        """Configuration of KFinance Client."""
+        """Configuration of KFinance Client.
+
+        :param refresh_token: users refresh token
+        :type refresh_token: str, Optional
+        :param client_id: users client id will be provided by support@kensho.com
+        :type client_id: str, Optional
+        :param private_key: users private key that corresponds to the registered public sent to support@kensho.com
+        :type private_key: str, Optional
+        :param thread_pool: the thread pool used to execute batch requests. The number of concurrent requests is
+        capped at 10. If no thread pool is provided, a thread pool with 10 max workers will be created when batch
+        requests are made.
+        :type thread_pool: ThreadPoolExecutor, Optional
+        :param api_host: the api host URL
+        :type api_host: str
+        :param api_version: the api version number
+        :type api_version: int
+        :param okta_host: the okta host URL
+        :type okta_host: str
+        :param okta_auth_server: the okta route for authentication
+        :type okta_auth_server: str
+        """
         if refresh_token is not None:
             self.refresh_token = refresh_token
             self._access_token_refresh_func: Callable[..., str] = (
@@ -48,10 +73,40 @@ class KFinanceApiClient:
         self.api_version = api_version
         self.okta_host = okta_host
         self.okta_auth_server = okta_auth_server
+        self._thread_pool = thread_pool
         self.url_base = f"{self.api_host}/api/v{self.api_version}/"
         self._access_token_expiry = 0
         self._access_token: str | None = None
         self.user_agent_source = "object_oriented"
+        self._batch_id: str | None = None
+        self._batch_size: str | None = None
+
+    @contextmanager
+    def batch_request_header(self, batch_size: int) -> Generator:
+        """Set batch id and batch size for batch request request headers"""
+        batch_id = str(uuid4())
+
+        self._batch_id = batch_id
+        self._batch_size = str(batch_size)
+
+        try:
+            yield
+        finally:
+            self._batch_id = None
+            self._batch_size = None
+
+    @property
+    def thread_pool(self) -> ThreadPoolExecutor:
+        """Returns the thread pool used to execute batch requests.
+
+        If the thread pool is not set, a thread pool with 10 max workers will be created
+         and returned.
+        """
+
+        if self._thread_pool is None:
+            self._thread_pool = ThreadPoolExecutor(max_workers=DEFAULT_MAX_WORKERS)
+
+        return self._thread_pool
 
     @property
     def access_token(self) -> str:
@@ -110,13 +165,21 @@ class KFinanceApiClient:
 
     def fetch(self, url: str) -> dict:
         """Does the request and auth"""
+
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.access_token}",
+            "User-Agent": f"kfinance/{kfinance_version} {self.user_agent_source}",
+        }
+        if self._batch_id is not None:
+            assert self._batch_size is not None
+            headers.update(
+                {"Kfinance-Batch-Id": self._batch_id, "Kfinance-Batch-Size": self._batch_size}
+            )
+
         response = requests.get(
             url,
-            headers={
-                "Content-Type": "application/json",
-                "Authorization": f"Bearer {self.access_token}",
-                "User-Agent": f"kfinance/{kfinance_version} {self.user_agent_source}",
-            },
+            headers=headers,
             timeout=60,
         )
         response.raise_for_status()

kfinance/kfinance.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from concurrent.futures import ThreadPoolExecutor
 from datetime import date, datetime, timezone
 from functools import cached_property
 from io import BytesIO
@@ -14,6 +15,7 @@ import numpy as np
 import pandas as pd
 from PIL.Image import Image, open as image_open
 
+from .batch_request_handling import add_methods_of_singular_class_to_iterable_class
 from .constants import HistoryMetadata, IdentificationTriple, LatestPeriods, YearAndQuarter
 from .fetch import (
     DEFAULT_API_HOST,
@@ -31,7 +33,10 @@ from .llm_tools import (
     langchain_tools,
     openai_tool_descriptions,
 )
-from .meta_classes import CompanyFunctionsMetaClass, DelegatedCompanyFunctionsMetaClass
+from .meta_classes import (
+    CompanyFunctionsMetaClass,
+    DelegatedCompanyFunctionsMetaClass,
+)
 from .prompt import PROMPT
 from .server_thread import ServerThread
 
@@ -917,6 +922,7 @@ class BusinessRelationships(NamedTuple):
         return f"{type(self).__module__}.{type(self).__qualname__} of {str(dictionary)}"
 
 
+@add_methods_of_singular_class_to_iterable_class(Company)
 class Companies(set):
     """Base class for representing a set of Companies"""
 
@@ -928,9 +934,11 @@ class Companies(set):
         :param company_ids: An iterable of S&P CIQ Company ids
         :type company_ids: Iterable[int]
         """
+        self.kfinance_api_client = kfinance_api_client
         super().__init__(Company(kfinance_api_client, company_id) for company_id in company_ids)
 
 
+@add_methods_of_singular_class_to_iterable_class(Security)
 class Securities(set):
     """Base class for representing a set of Securities"""
 
@@ -945,6 +953,7 @@ class Securities(set):
         super().__init__(Security(kfinance_api_client, security_id) for security_id in security_ids)
 
 
+@add_methods_of_singular_class_to_iterable_class(TradingItem)
 class TradingItems(set):
     """Base class for representing a set of Trading Items"""
 
@@ -958,14 +967,16 @@ class TradingItems(set):
         :param company_ids: An iterable of S&P CIQ Company ids
         :type company_ids: Iterable[int]
         """
+        self.kfinance_api_client = kfinance_api_client
         super().__init__(
             TradingItem(kfinance_api_client, trading_item_id)
             for trading_item_id in trading_item_ids
         )
 
 
+@add_methods_of_singular_class_to_iterable_class(Ticker)
 class Tickers(set):
-    """Base TickerSet class for representing a set of Tickers"""
+    """Base class for representing a set of Tickers"""
 
     def __init__(
         self,
@@ -1041,6 +1052,7 @@ class Client:
         refresh_token: Optional[str] = None,
         client_id: Optional[str] = None,
         private_key: Optional[str] = None,
+        thread_pool: Optional[ThreadPoolExecutor] = None,
         api_host: str = DEFAULT_API_HOST,
         api_version: int = DEFAULT_API_VERSION,
         okta_host: str = DEFAULT_OKTA_HOST,
@@ -1054,6 +1066,10 @@ class Client:
         :type client_id: str, Optional
         :param private_key: users private key that corresponds to the registered public sent to support@kensho.com
         :type private_key: str, Optional
+        :param thread_pool: the thread pool used to execute batch requests. The number of concurrent requests is
+        capped at 10. If no thread pool is provided, a thread pool with 10 max workers will be created when batch
+        requests are made.
+        :type thread_pool: ThreadPoolExecutor, Optional
         :param api_host: the api host URL
         :type api_host: str
         :param api_version: the api version number
@@ -1071,6 +1087,7 @@ class Client:
                 api_host=api_host,
                 api_version=api_version,
                 okta_host=okta_host,
+                thread_pool=thread_pool,
             )
         # method 2 keypair
         elif client_id is not None and private_key is not None:
@@ -1081,6 +1098,7 @@ class Client:
                 api_version=api_version,
                 okta_host=okta_host,
                 okta_auth_server=okta_auth_server,
+                thread_pool=thread_pool,
             )
         # method 3 automatic login getting a refresh token
         else:
@@ -1099,6 +1117,7 @@ class Client:
                 api_host=api_host,
                 api_version=api_version,
                 okta_host=okta_host,
+                thread_pool=thread_pool,
             )
             stdout.write("Login credentials received.\n")
 

kfinance/llm_tools.py

@@ -31,23 +31,25 @@ class Model(Enum):
 
 
 def get_latest(use_local_timezone: bool = True) -> LatestPeriods:
-    """Get the latest annual reporting year, latest quarterly reporting quarter and year, and current date. The output is a dictionary with the following schema::
+    """Get the latest annual reporting year, latest quarterly reporting quarter and year, and current date.
 
-    {
-        "annual": {
-            "latest_year": int
-        },
-        "quarterly": {
-            "latest_quarter": int,
-            "latest_year": int
-        },
-        "now": {
-            "current_year": int,
-            "current_quarter": int,
-            "current_month": int,
-            "current_date": str # in format Y-m-d
+    The output is a dictionary with the following schema::
+
+        {
+            "annual": {
+                "latest_year": int
+            },
+            "quarterly": {
+                "latest_quarter": int,
+                "latest_year": int
+            },
+            "now": {
+                "current_year": int,
+                "current_quarter": int,
+                "current_month": int,
+                "current_date": str # in format Y-m-d
+            }
         }
-    }
 
     Args:
         use_local_timezone: whether to use the local timezone of the user
@@ -86,12 +88,14 @@ def get_latest(use_local_timezone: bool = True) -> LatestPeriods:
 
 
 def get_n_quarters_ago(n: int) -> YearAndQuarter:
-    """Get the year and quarter corresponding to [n] quarters before the current quarter. The output is a dictionary with the following schema::
+    """Get the year and quarter corresponding to [n] quarters before the current quarter.
 
-    {
-        "year": int,
-        "quarter": int
-    }
+    The output is a dictionary with the following schema::
+
+        {
+            "year": int,
+            "quarter": int
+        }
 
     Args:
         n: number of quarters before the current quarter

kfinance/tests/test_batch_requests.py

@@ -0,0 +1,256 @@
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict
+from unittest import TestCase
+from unittest.mock import patch
+
+import numpy as np
+import pandas as pd
+import pytest
+import requests
+import requests_mock
+
+from kfinance.fetch import KFinanceApiClient
+from kfinance.kfinance import Companies, Company, Ticker, TradingItems
+
+
+@pytest.fixture(autouse=True)
+def mock_method():
+    with patch("kfinance.fetch.KFinanceApiClient.access_token", return_value="fake_access_token"):
+        yield
+
+
+class TestTradingItem(TestCase):
+    def setUp(self):
+        self.kfinance_api_client = KFinanceApiClient(refresh_token="fake_refresh_token")
+        self.kfinance_api_client_with_thread_pool = KFinanceApiClient(
+            refresh_token="fake_refresh_token", thread_pool=ThreadPoolExecutor(100)
+        )
+        self.test_ticker = Ticker(self.kfinance_api_client, "test")
+
+    def company_object_keys_as_company_id(self, company_dict: Dict[Company, Any]):
+        return dict(map(lambda company: (company.company_id, company_dict[company]), company_dict))
+
+    @requests_mock.Mocker()
+    def test_batch_request_property(self, m):
+        """GIVEN a kfinance group object like Companies
+        WHEN we batch request a property for each object in the group
+        THEN the batch request completes successfully and we get back a mapping of
+        company objects to the corresponding values."""
+
+        m.get(
+            "https://kfinance.kensho.com/api/v1/info/1001",
+            json={
+                "name": "Mock Company A, Inc.",
+                "city": "Mock City A",
+            },
+        )
+        m.get(
+            "https://kfinance.kensho.com/api/v1/info/1002",
+            json={
+                "name": "Mock Company B, Inc.",
+                "city": "Mock City B",
+            },
+        )
+
+        companies = Companies(self.kfinance_api_client, [1001, 1002])
+        result = companies.city
+        id_based_result = self.company_object_keys_as_company_id(result)
+
+        expected_id_based_result = {1001: "Mock City A", 1002: "Mock City B"}
+        self.assertDictEqual(id_based_result, expected_id_based_result)
+
+    @requests_mock.Mocker()
+    def test_batch_request_cached_properties(self, m):
+        """GIVEN a kfinance group object like Companies
+        WHEN we batch request a cached property for each object in the group
+        THEN the batch request completes successfully and we get back a mapping of
+        company objects to the corresponding values."""
+
+        m.get(
+            "https://kfinance.kensho.com/api/v1/securities/1001",
+            json={"securities": [101, 102, 103]},
+        )
+        m.get(
+            "https://kfinance.kensho.com/api/v1/securities/1002",
+            json={"securities": [104, 105, 106, 107]},
+        )
+        m.get("https://kfinance.kensho.com/api/v1/securities/1005", json={"securities": [108, 109]})
+
+        companies = Companies(self.kfinance_api_client, [1001, 1002, 1005])
+        result = companies.securities
+
+        id_based_result = self.company_object_keys_as_company_id(result)
+        for k, v in id_based_result.items():
+            id_based_result[k] = set(map(lambda s: s.security_id, v))
+
+        expected_id_based_result = {
+            1001: set([101, 102, 103]),
+            1002: set([104, 105, 106, 107]),
+            1005: set([108, 109]),
+        }
+
+        self.assertDictEqual(id_based_result, expected_id_based_result)
+
+    @requests_mock.Mocker()
+    def test_batch_request_function(self, m):
+        """GIVEN a kfinance group object like TradingItems
+        WHEN we batch request a function for each object in the group
+        THEN the batch request completes successfully and we get back a mapping of
+        trading item objects to the corresponding values."""
+
+        m.get(
+            "https://kfinance.kensho.com/api/v1/pricing/2/none/none/day/adjusted",
+            json={
+                "prices": [
+                    {"date": "2024-01-01", "close": "100.000000"},
+                    {"date": "2024-01-02", "close": "101.000000"},
+                ]
+            },
+        )
+        m.get(
+            "https://kfinance.kensho.com/api/v1/pricing/3/none/none/day/adjusted",
+            json={
+                "prices": [
+                    {"date": "2024-01-01", "close": "200.000000"},
+                    {"date": "2024-01-02", "close": "201.000000"},
+                ]
+            },
+        )
+
+        trading_items = TradingItems(self.kfinance_api_client, [2, 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"},
+            ],
+        }
+        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),
+            )
+
+    @requests_mock.Mocker()
+    def test_large_batch_request_property(self, m):
+        """GIVEN a kfinance group object like Companies with a very large size
+        WHEN we batch request a property for each object in the group
+        THEN the batch request completes successfully and we get back a mapping of
+        company objects to the corresponding values."""
+
+        m.get(
+            "https://kfinance.kensho.com/api/v1/info/1000",
+            json={
+                "name": "Test Inc.",
+                "city": "Test City",
+            },
+        )
+
+        BATCH_SIZE = 100
+        companies = Companies(self.kfinance_api_client, [1000] * BATCH_SIZE)
+        result = list(companies.city.values())
+        expected_result = ["Test City"] * BATCH_SIZE
+        self.assertEqual(result, expected_result)
+
+    @requests_mock.Mocker()
+    def test_batch_request_property_404(self, m):
+        """GIVEN a kfinance group object like Companies
+        WHEN we batch request a property for each object in the group and one of the
+        property requests returns a 404
+        THEN the batch request completes successfully and we get back a mapping of
+        company objects to the corresponding property value or None when the request for
+        that property returns a 404"""
+
+        m.get(
+            "https://kfinance.kensho.com/api/v1/info/1001",
+            json={
+                "name": "Mock Company A, Inc.",
+                "city": "Mock City A",
+            },
+        )
+        m.get("https://kfinance.kensho.com/api/v1/info/1002", status_code=404)
+
+        companies = Companies(self.kfinance_api_client, [1001, 1002])
+        result = companies.city
+        id_based_result = self.company_object_keys_as_company_id(result)
+
+        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_400(self, m):
+        """GIVEN a kfinance group object like Companies
+        WHEN we batch request a property for each object in the group and one of the
+        property requests returns a 400
+        THEN the batch request returns a 400"""
+
+        m.get(
+            "https://kfinance.kensho.com/api/v1/info/1001",
+            json={
+                "name": "Mock Company A, Inc.",
+                "city": "Mock City A",
+            },
+        )
+        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
+
+        self.assertEqual(e.exception.response.status_code, 400)
+
+    @requests_mock.Mocker()
+    def test_batch_request_500(self, m):
+        """GIVEN a kfinance group object like Companies
+        WHEN we batch request a property for each object in the group and one of the
+        property requests returns a 500
+        THEN the batch request returns a 500"""
+
+        m.get(
+            "https://kfinance.kensho.com/api/v1/info/1001",
+            json={
+                "name": "Mock Company A, Inc.",
+                "city": "Mock City A",
+            },
+        )
+        m.get("https://kfinance.kensho.com/api/v1/info/1002", status_code=500)
+
+        with self.assertRaises(requests.exceptions.HTTPError) as e:
+            companies = Companies(self.kfinance_api_client, [1001, 1002])
+            _ = companies.city
+
+        self.assertEqual(e.exception.response.status_code, 500)
+
+    @requests_mock.Mocker()
+    def test_batch_request_property_with_thread_pool(self, m):
+        """GIVEN a kfinance group object like Companies and an api client instantiated
+        with a passed-in ThreadPool
+        WHEN we batch request a property for each object in the group
+        THEN the batch request completes successfully and we get back a mapping of
+        company objects to corresponding values"""
+
+        m.get(
+            "https://kfinance.kensho.com/api/v1/info/1001",
+            json={
+                "name": "Mock Company A, Inc.",
+                "city": "Mock City A",
+            },
+        )
+
+        companies = Companies(self.kfinance_api_client_with_thread_pool, [1001])
+        result = companies.city
+        id_based_result = self.company_object_keys_as_company_id(result)
+
+        expected_id_based_result = {1001: "Mock City A"}
+        self.assertDictEqual(id_based_result, expected_id_based_result)

kfinance/tool_schemas.py

@@ -16,7 +16,9 @@ class GetNQuartersAgoInput(BaseModel):
 
 
 class GetCompanyIdFromIdentifier(BaseModel):
-    ticker_str: str = Field(description="The ticker")
+    identifier: str = Field(
+        description="The identifier, which can be a ticker symbol, ISIN, or CUSIP"
+    )
 
 
 class GetSecurityIdFromIdentifier(BaseModel):

kfinance/version.py

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

kensho_kfinance-1.1.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-kensho_kfinance-1.1.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-1.1.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=HZt-UygSOIhqMa27Xxffm_R3TlmIPHmdt3jBYvaZPxY,390
-kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/constants.py,sha256=SJfI3K2gS0N-M3-rHIMizcxjyTz_iWBc7UYtauUOjDg,47338
-kfinance/fetch.py,sha256=n34L_uM53FVN0cWz8aVqnst2bfFL2D9zIUwZTXze-tY,15736
-kfinance/kfinance.py,sha256=4yVNoi1PMEwMUwYrcz4AypHu-TXfTPaZDzuykDB4Qs0,44669
-kfinance/llm_tools.py,sha256=PehZgJN1qLXOu96Rp5CpZ4nrT9rLrzuedugTfBxHZr8,30597
-kfinance/meta_classes.py,sha256=ryncusGDe48gG31a-Ldx1ApJ-ZPRFJvjC18jry7TOVE,15980
-kfinance/prompt.py,sha256=PtVB8c_FcSlVdyGgByAnIFGzuUuBaEjciCqnBJl1hSQ,25133
-kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
-kfinance/tool_schemas.py,sha256=YaIXISqeE5WX2moWPXopwqF9X6hr5u-0rRVJuBVcaTo,5579
-kfinance/version.py,sha256=UNO7UaKPam6Zugzw6NMt_RQBnRzrv9GVeKUjWt-tl6I,511
-kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/tests/test_fetch.py,sha256=gYSYDSsMUHpwwMODN0_g7kQQAEWq_jsucIRiqhBjAcA,12981
-kfinance/tests/test_objects.py,sha256=egXkhfoK2MepZdXtrBxzWxWni7f-zVCefUbnyDnWDOE,22554
-kensho_kfinance-1.1.0.dist-info/METADATA,sha256=rjS8yKw0aB18MiJg34AA0kjJlpbNzvRudvVSrevYSwM,2814
-kensho_kfinance-1.1.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-kensho_kfinance-1.1.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-1.1.0.dist-info/RECORD,,