kensho-kfinance 2.1.2__py3-none-any.whl → 2.2.2__py3-none-any.whl

{kensho_kfinance-2.1.2.dist-info → kensho_kfinance-2.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.1.2
+Version: 2.2.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
@@ -28,7 +28,11 @@ Requires-Dist: requests<3,>=2.22.0
 Requires-Dist: urllib3>=1.21.1
 Provides-Extra: dev
 Requires-Dist: coverage<8,>=7.6.10; extra == "dev"
+Requires-Dist: ipykernel<7,>=6.29; extra == "dev"
 Requires-Dist: mypy<2,>=1.15.0; extra == "dev"
+Requires-Dist: nbconvert<8,>=7.16; extra == "dev"
+Requires-Dist: nbformat<6,>5.10; extra == "dev"
+Requires-Dist: nbqa<2,>1.9; extra == "dev"
 Requires-Dist: pytest<7,>=6.1.2; extra == "dev"
 Requires-Dist: pytest-cov<7,>=6.0.0; extra == "dev"
 Requires-Dist: requests_mock<2,>=1.12; extra == "dev"
@@ -57,6 +61,8 @@ 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).
 
+We also provide an [interactive notebook](usage_examples.ipynb) that demonstrates some usage examples.
+
 # Versioning
 The kFinance uses semantic versioning (major, minor, patch). 
 To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 

{kensho_kfinance-2.1.2.dist-info → kensho_kfinance-2.2.2.dist-info}/RECORD

@@ -1,43 +1,42 @@
-kensho_kfinance-2.1.2.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-2.1.2.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=kXKUnP2knjAi0OrJ-mptiTjuXsPqI8S3e2SQ96CCibs,931
+kensho_kfinance-2.2.2.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-2.2.2.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=eX36Pj6mDG2B6AtnHpP5FAJ14X-8XqF0fNRTYOGClXw,1140
 kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/batch_request_handling.py,sha256=8J7rUPu1AepqWWdRr3ucJQLnZUjitirjjv5L5YG4nFg,5489
-kfinance/constants.py,sha256=_MwkxWSqMKhBDvmPk4kL3tfWm-z54dVlXeVvbaiHEqg,48650
-kfinance/fetch.py,sha256=rl7WI8WSphA6XPt2DLBVdHc5aU9gPNdIiYNDkKPVrUE,22063
-kfinance/kfinance.py,sha256=b86qjy_hbxQ7sKDwcOPfXipaBiXgYsK4nJO2nJouTDs,53294
-kfinance/meta_classes.py,sha256=tGZb_6GOLiWJXMx4MYDSHzcxTnBGNp3lLdXlsxat_Mw,15858
+kfinance/batch_request_handling.py,sha256=p6p_G4_BL06GgeKlh7P1k9CUqOMahWCLEw1NoBwbLvU,5698
+kfinance/constants.py,sha256=4vj0WA0xupEJexvnI-ap6LFHXEf6dn8jQwJlxz8cGTs,48767
+kfinance/fetch.py,sha256=fguxYy5rjLQKNkmP7gsvZUJtmt9uDNxg6LN9FRJTAVQ,22936
+kfinance/kfinance.py,sha256=_U69k0Dcwkw1B_lzaUZy8N2-c-v93ZKoUAVVZb6wBUM,52758
+kfinance/meta_classes.py,sha256=nwqHRi8IFa4WLFAZpX4a6htR47doK3_qVLnYBOylQV0,20482
 kfinance/prompt.py,sha256=PtVB8c_FcSlVdyGgByAnIFGzuUuBaEjciCqnBJl1hSQ,25133
 kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
-kfinance/version.py,sha256=R_mUEqlkeWeuDiw8DRbHmYUvRxDtmQQJqhTpV8pds-Y,511
+kfinance/version.py,sha256=YDBduKhVnvbZfZTbXbsjQMbxTwgIIXIZ646Mj9YV074,511
 kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/tests/conftest.py,sha256=voB-w8P_6L3Nel3rdgylXKe5WWaS1q7nCFt1O04uqoY,948
-kfinance/tests/test_batch_requests.py,sha256=hL3VfbmyVgL2KJ5blGRHhYKrnlIfICjCvXmvtx2zsV8,10149
+kfinance/tests/test_batch_requests.py,sha256=uXJF2IcRdyBm5SthwIUHMKtkGZ21MY84pg_k1JeSNOY,11430
 kfinance/tests/test_client.py,sha256=O7icZCSDhlQ9WGhzoXlpiSvbuA-mQNJHBYVsilyP_dE,2209
-kfinance/tests/test_fetch.py,sha256=YeehfsXHpEBgyLdaBTJ6dE1bGNhq_A_JvZmy-iQ-gp4,12441
+kfinance/tests/test_example_notebook.py,sha256=XhDAJp3H5Y6usLAt3k4Ug4W3H6gLyh68nzmoWgOOLn4,6441
+kfinance/tests/test_fetch.py,sha256=O9qOsffQYJPSAR1X_P6CNoA0Buyq2kx4vfS0FOc2Goc,13564
 kfinance/tests/test_group_objects.py,sha256=SoMEZmkG4RYdgWOAwxLHHtzIQho92KM01YbQXPUg578,1689
-kfinance/tests/test_objects.py,sha256=egXkhfoK2MepZdXtrBxzWxWni7f-zVCefUbnyDnWDOE,22554
-kfinance/tests/test_tools.py,sha256=h5bScYQBYD9IQ8eAz2L6YB2rLHixqM4SXPfWjm17jB0,16187
+kfinance/tests/test_objects.py,sha256=PpB3q4UPi9ctRznq48Fy6sJUsOEqdAWzMzee1BYORX4,24001
+kfinance/tests/test_tools.py,sha256=fTN43Y8fX8l8Yyw65XJmn_xUIbrTLaPvrsuBEdKPqK0,15234
 kfinance/tool_calling/README.md,sha256=omJq7Us6r4U45QB7hRpLjRJ5BMalCkZkh4uXBjTbJXc,2022
-kfinance/tool_calling/__init__.py,sha256=GDEeK2zM2tOfYam6ejwYACXecoRdlkRve_ZC5VTKugo,2038
+kfinance/tool_calling/__init__.py,sha256=ewTzpR4S9mzCtSRpfK7WldDX78VSRKFta-s_zBsmamA,1744
 kfinance/tool_calling/get_business_relationship_from_identifier.py,sha256=CipXvyqEjPm6BXYP0CA9Kp1BIyiIEm7abp85x1zXRV4,1472
 kfinance/tool_calling/get_capitalization_from_identifier.py,sha256=TdWdJDeI-jSL-1YfhnnwIA9D1SXobidvoHrjK42QmqQ,1521
-kfinance/tool_calling/get_company_id_from_identifier.py,sha256=GPakqIA27-RoqKFjM7W2nd3xp4v3utIPpH932BNNAlk,577
 kfinance/tool_calling/get_cusip_from_ticker.py,sha256=houhGCYXoSzaaTtCvOBf3pPsYiSbcV1Ej5nAyGuMWcU,644
 kfinance/tool_calling/get_earnings_call_datetimes_from_identifier.py,sha256=Zp7gHP-z2ePu484wWx4xw89hl0z7NLcG3qliJT-6rUo,782
 kfinance/tool_calling/get_financial_line_item_from_identifier.py,sha256=bMK-GUMz_wmJ-7iFS72sM8AvvUvR83JYRWzYtr9Fofw,2153
 kfinance/tool_calling/get_financial_statement_from_identifier.py,sha256=9ouzC43skA78uI3dh3bvtM86db5RGxuWQAAJ24y-kBM,1906
 kfinance/tool_calling/get_history_metadata_from_identifier.py,sha256=kKIInfRC1Plf-Wnx9cmaJ46RRABm6zn3F5_8qAdqrBg,728
-kfinance/tool_calling/get_info_from_identifier.py,sha256=MtcC3RSbKrbOML381rkRcPXcAVXOmhqltpF_XVT-r-w,751
+kfinance/tool_calling/get_info_from_identifier.py,sha256=PRhSYpYs_iUcIVFGYCMN_7QJyhewua7c7pqngPIp-qg,766
 kfinance/tool_calling/get_isin_from_ticker.py,sha256=2fJBcA-rNGbVOQmQ7qJEYxqejQwJ6nyWOBSFlzxG7dY,638
 kfinance/tool_calling/get_latest.py,sha256=btGeVBmvX5QJutzrKfE6spatGGejDuHxtq53NoAaGNk,786
 kfinance/tool_calling/get_n_quarters_ago.py,sha256=A0ilwPKUqU0YYQSz3gNsVF0Jy4YttXrSaDhYj7y8GHA,713
 kfinance/tool_calling/get_prices_from_identifier.py,sha256=ViJkwLDvStB7grc8RuoKSDXQM399Wru4-OY3E8k1l_U,1882
-kfinance/tool_calling/get_security_id_from_identifier.py,sha256=oxFVc7YgKMug8VofLGt-w2ZxN_Z8VaRnHC5YdaIoFNU,581
-kfinance/tool_calling/get_trading_item_id_from_identifier.py,sha256=BYVb061vIj2S40tS7pkjxAzbVIDU6feMCwr0DNdA_4k,596
+kfinance/tool_calling/resolve_identifier.py,sha256=npslr6bBCu0qEDV1-8d24F5OC3nQ1KBMphuMbHVC1AU,626
 kfinance/tool_calling/shared_models.py,sha256=K-NPQyE_7Ew6Cs0zxG1xO2O47gp5uDHdHtWD7wUDZX4,2132
-kensho_kfinance-2.1.2.dist-info/METADATA,sha256=S_IUpoLLbFir0jT_-L7opp8WVNG21-eW6Vmf9AOCgSE,3141
-kensho_kfinance-2.1.2.dist-info/WHEEL,sha256=DnLRTWE75wApRYVsjgc6wsVswC54sMSJhAEd4xhDpBk,91
-kensho_kfinance-2.1.2.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-2.1.2.dist-info/RECORD,,
+kensho_kfinance-2.2.2.dist-info/METADATA,sha256=VOmB9CZIcpr2DI5tJBZuWnR039oK_iRTN4cvDFco4RQ,3436
+kensho_kfinance-2.2.2.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+kensho_kfinance-2.2.2.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-2.2.2.dist-info/RECORD,,

{kensho_kfinance-2.1.2.dist-info → kensho_kfinance-2.2.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.4.0)
+Generator: setuptools (80.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

kfinance/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v2.2.2
+- Add segments
+
+## v2.2.1
+- Make number of employees optional to reflect backend changes
+
+## v2.2.0
+- Replace get company id, get security id, get trading item id tools with resolve identifier tool
+
 ## v2.1.2
 - Allow batch executor to handle multiple requests
 

kfinance/batch_request_handling.py

@@ -1,4 +1,4 @@
-from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import Future
 import functools
 from functools import cached_property
 import threading
@@ -55,36 +55,26 @@ def add_methods_of_singular_class_to_iterable_class(singular_cls: Type[T]) -> Ca
             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:
-            kfinance_api_client = self.kfinance_api_client
-            with kfinance_api_client.batch_request_header(batch_size=len(self)):
-                results = dict(
-                    zip(
-                        self,
-                        [
-                            process_in_thread_pool(
-                                kfinance_api_client.thread_pool, method, obj, *args, **kwargs
-                            )
-                            for obj in self
-                        ],
+            with self.kfinance_api_client.batch_request_header(batch_size=len(self)):
+                futures = []
+                for obj in self:
+                    # Acquire throttle before submitting the task
+                    throttle.acquire()
+                    future = self.kfinance_api_client.thread_pool.submit(
+                        method, obj, *args, **kwargs
                     )
-                )
+                    # On success or failure, release the throttle.
+                    # This releases the throttle before the
+                    # `resolve_future_with_error_handling` call.
+                    future.add_done_callback(lambda f: throttle.release())
+                    futures.append(future)
+
+                results = {}
+                for obj, future in zip(self, futures):
+                    results[obj] = resolve_future_with_error_handling(future)
 
             return results
 
@@ -135,3 +125,18 @@ def add_methods_of_singular_class_to_iterable_class(singular_cls: Type[T]) -> Ca
         return iterable_cls
 
     return decorator
+
+
+def resolve_future_with_error_handling(future: Future) -> Any:
+    """Return the result of a future with error handling for non-200 status codes.
+
+    If request returned a 404, return None. Otherwise, raise the error.
+    """
+    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

kfinance/constants.py

@@ -62,6 +62,13 @@ class StatementType(StrEnum):
     cf = "cashflow"
 
 
+class SegmentType(StrEnum):
+    """The type of segment"""
+
+    business = "business"
+    geographic = "geographic"
+
+
 class BusinessRelationshipType(StrEnum):
     """The type of business relationship"""
 

kfinance/fetch.py

@@ -15,6 +15,7 @@ from .constants import (
     Periodicity,
     PeriodType,
     Permission,
+    SegmentType,
 )
 
 
@@ -305,6 +306,27 @@ class KFinanceApiClient:
         )
         return self.fetch(url)
 
+    def fetch_segments(
+        self,
+        company_id: int,
+        segment_type: SegmentType,
+        period_type: Optional[PeriodType] = None,
+        start_year: Optional[int] = None,
+        end_year: Optional[int] = None,
+        start_quarter: Optional[int] = None,
+        end_quarter: Optional[int] = None,
+    ) -> dict:
+        """Get a specified segment type for a specified duration."""
+        url = (
+            f"{self.url_base}segments/{company_id}/{segment_type}/"
+            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'}/"
+            f"{end_quarter if end_quarter is not None else 'none'}"
+        )
+        return self.fetch(url)
+
     def fetch_price_chart(
         self,
         trading_item_id: int,

kfinance/kfinance.py

@@ -262,7 +262,7 @@ class Company(CompanyFunctionsMetaClass):
     def info(self) -> dict:
         """Get the company info
 
-        :return: a dict with containing: name, status, type, simple industry, number of employees, founding date, webpage, address, city, zip code, state, country, & iso_country
+        :return: a dict with containing: name, status, type, simple industry, number of employees (if available), founding date, webpage, address, city, zip code, state, country, & iso_country
         :rtype: dict
         """
         return self.kfinance_api_client.fetch_info(self.company_id)
@@ -304,11 +304,11 @@ class Company(CompanyFunctionsMetaClass):
         return self.info["simple_industry"]
 
     @property
-    def number_of_employees(self) -> str:
-        """Get the number of employees the company has
+    def number_of_employees(self) -> str | None:
+        """Get the number of employees the company has (if available)
 
         :return: how many employees the company has
-        :rtype: str
+        :rtype: str | None
         """
         return self.info["number_of_employees"]
 
@@ -537,11 +537,32 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
 
     @property
     def id_triple(self) -> IdentificationTriple:
-        """Returns a unique identifier triple for the Ticker object."""
+        """Returns a unique identification triple for the Ticker object.
+
+        :return: an identification triple consisting of company_id, security_id, and trading_item_id
+        :rtype: IdentificationTriple
+        """
+
+        if self._company_id is None or self._security_id is None or self._trading_item_id is None:
+            if self._identifier is None:
+                raise RuntimeError(
+                    "Fetching the id triple of a Ticker requires an identifier "
+                    "(ticker, CUSIP, or ISIN)."
+                )
+            id_triple = self.kfinance_api_client.fetch_id_triple(
+                identifier=self._identifier, exchange_code=self.exchange_code
+            )
+            self._company_id = id_triple["company_id"]
+            self._security_id = id_triple["security_id"]
+            self._trading_item_id = id_triple["trading_item_id"]
+            assert self._company_id
+            assert self._security_id
+            assert self._trading_item_id
+
         return IdentificationTriple(
-            company_id=self.company_id,
-            security_id=self.security_id,
-            trading_item_id=self.trading_item_id,
+            company_id=self._company_id,
+            security_id=self._security_id,
+            trading_item_id=self._trading_item_id,
         )
 
     def __hash__(self) -> int:
@@ -570,79 +591,32 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
 
         return f"{type(self).__module__}.{type(self).__qualname__} of {', '.join(str_attributes)}"
 
-    def set_identification_triple(self) -> None:
-        """Get & set company_id, security_id, & trading_item_id for ticker with an exchange"""
-        if self._identifier is None:
-            raise RuntimeError(
-                "Ticker.set_identification_triple was called with a identifier set to None"
-            )
-        else:
-            id_triple = self.kfinance_api_client.fetch_id_triple(
-                self._identifier, self.exchange_code
-            )
-            self.company_id = id_triple["company_id"]
-            self.security_id = id_triple["security_id"]
-            self.trading_item_id = id_triple["trading_item_id"]
-
-    def set_company_id(self) -> int:
-        """Set the company id for the object
-
-        :return: the CIQ company id
-        :rtype: int
-        """
-        self.set_identification_triple()
-        return self.company_id
-
-    def set_security_id(self) -> int:
-        """Set the security id for the object
-
-        :return: the CIQ security id
-        :rtype: int
-        """
-        self.set_identification_triple()
-        return self.security_id
-
-    def set_trading_item_id(self) -> int:
-        """Set the trading item id for the object
-
-        :return: the CIQ trading item id
-        :rtype: int
-        """
-        self.set_identification_triple()
-        return self.trading_item_id
-
-    @cached_property
+    @property
     def company_id(self) -> int:
         """Get the company id for the object
 
         :return: the CIQ company id
         :rtype: int
         """
-        if self._company_id:
-            return self._company_id
-        return self.set_company_id()
+        return self.id_triple.company_id
 
-    @cached_property
+    @property
     def security_id(self) -> int:
         """Get the CIQ security id for the object
 
         :return: the CIQ security id
         :rtype: int
         """
-        if self._security_id:
-            return self._security_id
-        return self.set_security_id()
+        return self.id_triple.security_id
 
-    @cached_property
+    @property
     def trading_item_id(self) -> int:
         """Get the CIQ trading item id for the object
 
         :return: the CIQ trading item id
         :rtype: int
         """
-        if self._trading_item_id:
-            return self._trading_item_id
-        return self.set_trading_item_id()
+        return self.id_triple.trading_item_id
 
     @cached_property
     def primary_security(self) -> Security:
@@ -711,7 +685,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
     def info(self) -> dict:
         """Get the company info for the ticker
 
-        :return: a dict with containing: name, status, type, simple industry, number of employees, founding date, webpage, address, city, zip code, state, country, & iso_country
+        :return: a dict with containing: name, status, type, simple industry, number of employees (if available), founding date, webpage, address, city, zip code, state, country, & iso_country
         :rtype: dict
         """
         return self.company.info
@@ -753,11 +727,11 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         return self.company.simple_industry
 
     @property
-    def number_of_employees(self) -> str:
-        """Get the number of employees the company has
+    def number_of_employees(self) -> str | None:
+        """Get the number of employees the company has (if available)
 
         :return: how many employees the company has
-        :rtype: str
+        :rtype: str | None
         """
         return self.company.number_of_employees
 

kfinance/meta_classes.py

@@ -7,7 +7,7 @@ from cachetools import LRUCache, cached
 import numpy as np
 import pandas as pd
 
-from .constants import LINE_ITEMS, BusinessRelationshipType, PeriodType
+from .constants import LINE_ITEMS, BusinessRelationshipType, PeriodType, SegmentType
 from .fetch import KFinanceApiClient
 
 
@@ -304,6 +304,114 @@ class CompanyFunctionsMetaClass:
         )
         return df.set_index("date")[[column_to_extract]].apply(pd.to_numeric).replace(np.nan, None)
 
+    def _segments(
+        self,
+        segment_type: SegmentType,
+        period_type: Optional[PeriodType] = None,
+        start_year: Optional[int] = None,
+        end_year: Optional[int] = None,
+        start_quarter: Optional[int] = None,
+        end_quarter: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Get the company's segments"""
+        try:
+            self.validate_inputs(
+                start_year=start_year,
+                end_year=end_year,
+                start_quarter=start_quarter,
+                end_quarter=end_quarter,
+            )
+        except ValueError:
+            return pd.DataFrame()
+
+        results = self.kfinance_api_client.fetch_segments(
+            company_id=self.company_id,
+            segment_type=segment_type,
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        )["segments"]
+
+        period_name = (
+            "Year" if (period_type == PeriodType.annual or period_type is None) else "Period"
+        )
+
+        # flatten the nested dictionary and return as a DataFrame
+        rows = []
+        for period, segments in results.items():
+            for segment_name, line_items in segments.items():
+                for line_item, value in line_items.items():
+                    rows.append([period, segment_name, line_item, value])
+        return pd.DataFrame(
+            rows, columns=[period_name, "Segment Name", "Line Item", "Value"]
+        ).replace(np.nan, None)
+
+    def business_segments(
+        self,
+        period_type: Optional[PeriodType] = None,
+        start_year: Optional[int] = None,
+        end_year: Optional[int] = None,
+        start_quarter: Optional[int] = None,
+        end_quarter: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Retrieves the templated line of business segments for a given period_type, start_year, start_quarter, end_year and end_quarter.
+
+        :param period_type: The period_type requested for. Can be “annual”, “quarterly”, "ytd". Defaults to “annual” when start_quarter and end_quarter are None.
+        :type start_year: PeriodType, optional
+        :param start_year: The starting calendar year, defaults to None
+        :type start_year: int, optional
+        :param end_year: The ending calendar year, defaults to None
+        :type end_year: int, optional
+        :param start_quarter: The starting calendar quarter, defaults to None
+        :type start_quarter: int, optional
+        :param end_quarter: The ending calendar quarter, defaults to None
+        :type end_quarter: int, optional
+        :return: A DataFrame with `Year`/`Period`, `Segment Name`, `Line Item` and `Value` column.
+        :rtype: pd.DataFrame
+        """
+        return self._segments(
+            segment_type=SegmentType.business,
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        )
+
+    def geographic_segments(
+        self,
+        period_type: Optional[PeriodType] = None,
+        start_year: Optional[int] = None,
+        end_year: Optional[int] = None,
+        start_quarter: Optional[int] = None,
+        end_quarter: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Retrieves the templated geographic segments for a given company for a given period_type, start_year, start_quarter, end_year and end_quarter.
+
+        :param period_type: The period_type requested for. Can be “annual”, “quarterly”, "ytd". Defaults to “annual” when start_quarter and end_quarter are None.
+        :type start_year: PeriodType, optional
+        :param start_year: The starting calendar year, defaults to None
+        :type start_year: int, optional
+        :param end_year: The ending calendar year, defaults to None
+        :type end_year: int, optional
+        :param start_quarter: The starting calendar quarter, defaults to None
+        :type start_quarter: int, optional
+        :param end_quarter: The ending calendar quarter, defaults to None
+        :type end_quarter: int, optional
+        :return: A DataFrame with `Year`/`Period`, `Segment Name`, `Line Item` and `Value` column.
+        :rtype: pd.DataFrame
+        """
+        return self._segments(
+            segment_type=SegmentType.geographic,
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        )
+
 
 for line_item in LINE_ITEMS:
     line_item_name = line_item["name"]

kfinance/tests/test_batch_requests.py

@@ -1,7 +1,8 @@
 from concurrent.futures import ThreadPoolExecutor
+import time
 from typing import Any, Dict
 from unittest import TestCase
-from unittest.mock import patch
+from unittest.mock import PropertyMock, patch
 
 import numpy as np
 import pandas as pd
@@ -9,6 +10,7 @@ import pytest
 import requests
 import requests_mock
 
+from kfinance.batch_request_handling import MAX_WORKERS_CAP
 from kfinance.fetch import KFinanceApiClient
 from kfinance.kfinance import Companies, Company, Ticker, TradingItems
 
@@ -260,3 +262,33 @@ class TestTradingItem(TestCase):
 
         expected_id_based_result = {1001: "Mock City A"}
         self.assertDictEqual(id_based_result, expected_id_based_result)
+
+    @patch.object(Company, "info", new_callable=PropertyMock)
+    def test_batch_requests_processed_in_parallel(self, mock_value: PropertyMock):
+        """
+        WHEN a batch request gets processed
+        THEN the requests are handled in parallel not sequentially.
+        """
+
+        sleep_duration = 0.05
+
+        def mock_info_with_sleep() -> dict[str, str]:
+            """Mock an info call with a short sleep"""
+            time.sleep(sleep_duration)
+            return {"city": "Cambridge"}
+
+        mock_value.side_effect = mock_info_with_sleep
+
+        # Create tasks up to the MAX_WORKERS_CAP (max number of parallel tasks)
+        companies = Companies(
+            self.kfinance_api_client_with_thread_pool, [i for i in range(MAX_WORKERS_CAP)]
+        )
+
+        start = time.perf_counter()
+        result = companies.city
+        end = time.perf_counter()
+        assert len(result) == MAX_WORKERS_CAP
+        # Check that the requests run faster than sequential.
+        # In practice, the requests should take barely more than the `sleep_duration` but timing
+        # based tests can be flaky, especially in CI.
+        assert end - start < MAX_WORKERS_CAP * sleep_duration

kfinance/tests/test_example_notebook.py

@@ -0,0 +1,194 @@
+from pathlib import Path
+import subprocess
+import sys
+from textwrap import dedent
+import uuid
+
+from nbconvert.preprocessors import ExecutePreprocessor
+import nbformat
+import pytest
+
+
+@pytest.fixture(scope="session")
+def jupyter_kernel_name() -> str:
+    """Create a jupyter kernel for a test run and yield its name.
+
+    The kernel gets removed at the end of the test run.
+    """
+
+    kernel_name = f"test-kfinance-kernel-{uuid.uuid4().hex[:8]}"
+
+    # Install a new kernel pointing to the current interpreter.
+    subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "ipykernel",
+            "install",
+            "--user",
+            "--name",
+            kernel_name,
+            "--display-name",
+            f"Python ({kernel_name})",
+        ],
+        check=True,
+    )
+
+    yield kernel_name
+
+    # Remove the kernel after the test.
+    subprocess.run(
+        [sys.executable, "-m", "jupyter", "kernelspec", "uninstall", "-f", kernel_name], check=True
+    )
+
+
+def test_run_notebook(jupyter_kernel_name: str):
+    """
+    GIVEN the usage_examples.ipynb notebook
+    WHEN the notebook gets run with a mock client and mock responses
+    THEN all cells of the notebook complete without errors.
+    """
+
+    # Create a replacement startup cell for the normal notebook client init.
+    # This cell contains:
+    # - setup of a mock client
+    # - mocks for all calls made by the client while executing the notebook
+    startup_cell_code = dedent("""
+        from datetime import datetime
+        from kfinance.kfinance import Client
+        kfinance_client = Client(refresh_token="foo")
+        api_client = kfinance_client.kfinance_api_client
+        # Set access token so that the client doesn't try to fetch it.
+        api_client._access_token = "foo"
+        api_client._access_token_expiry = datetime(2100, 1, 1).timestamp()
+
+        # Mock out all necessary requests with requests_mock
+        import requests_mock
+        mocker = requests_mock.Mocker()
+        mocker.start()
+
+        id_triple_resp = {
+            "trading_item_id": 2629108,
+            "security_id": 2629107,
+            "company_id": 21719
+        }
+
+        # spgi = kfinance_client.ticker("SPGI")
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/id/SPGI",
+            json=id_triple_resp
+        )
+
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/info/21719",
+            json={"name": "S&P Global Inc."}
+        )
+
+        balance_sheet_resp = {
+            "statements": {
+                "2022Q3": {"Cash And Equivalents": "1387000000.000000"},
+                "2022Q4": {"Cash And Equivalents": "1286000000.000000"}
+            }
+        }
+
+        # spgi.balance_sheet()
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/statements/21719/balance_sheet/none/none/none/none/none",
+            json=balance_sheet_resp
+        )
+
+        # spgi.balance_sheet(period_type=PeriodType.annual, start_year=2010, end_year=2019)
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/statements/21719/balance_sheet/annual/2010/2019/none/none",
+            json=balance_sheet_resp
+        )
+
+        # kfinance_client.ticker("JPM").balance_sheet()
+        # (leads to fetching SPGI balance sheet when requesting JPM because they return the same
+        # company id)
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/id/JPM",
+            json=id_triple_resp
+        )
+
+        # spgi.net_income(period_type=PeriodType.annual, start_year=2010, end_year=2019)
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/line_item/21719/net_income/annual/2010/2019/none/none",
+            json={"line_item": {"2010": "828000000.000000"}}
+        )
+
+        prices_resp = {
+            "prices": [
+                {
+                    "date": "2024-05-20",
+                    "open": "439.540000",
+                    "high": "441.570000",
+                    "low": "437.000000",
+                    "close": "437.740000",
+                    "volume": "1080006"
+                }
+            ]
+        }
+
+        # spgi.history()
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/pricing/2629108/none/none/day/adjusted",
+            json=prices_resp
+        )
+
+        # spgi.history(
+        #     periodicity=Periodicity.month,
+        #     adjusted=False,
+        #     start_date="2010-01-01",
+        #     end_date="2019-12-31"
+        # )
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/pricing/2629108/2010-01-01/2019-12-31/month/unadjusted",
+            json=prices_resp
+        )
+
+        # spgi.price_chart(
+        #     periodicity=Periodicity.month,
+        #     adjusted=False,
+        #     start_date="2010-01-01",
+        #     end_date="2019-12-31"
+        # )
+        mocker.get(
+            url='https://kfinance.kensho.com/api/v1/price_chart/2629108/2010-01-01/2019-12-31/month/unadjusted',
+            content=b"",
+            headers={'Content-Type': 'image/png'}
+        )
+        # Mock out image_open so that we don't have to return an actual png.
+        from unittest.mock import MagicMock
+        import kfinance.kfinance
+        kfinance.kfinance.image_open = MagicMock()
+    """)
+
+    # Load the notebook
+    notebook_path = Path(Path(__file__).parent.parent.parent, "usage_examples.ipynb")
+    with notebook_path.open() as f:
+        nb = nbformat.read(f, as_version=4)
+
+    # Set up the notebook executor
+    ep = ExecutePreprocessor(timeout=600, kernel_name=jupyter_kernel_name)
+
+    # Identify the start of the example section
+    example_sections_heading = "## Example functions"
+    examples_start_cell_id = None
+    for idx, cell in enumerate(nb.cells):
+        if cell["source"] == example_sections_heading:
+            examples_start_cell_id = idx
+
+    if not examples_start_cell_id:
+        raise ValueError(
+            f"Did not find a cell with content {example_sections_heading} that "
+            f"indicates the start of the examples."
+        )
+
+    # Combine the startup cell with the start of the examples
+    # i.e. toss everything before the examples start
+    nb.cells = [nbformat.v4.new_code_cell(startup_cell_code)] + nb.cells[examples_start_cell_id:]
+
+    # Run the notebook.
+    # The test passes if the notebook runs without errors.
+    ep.preprocess(nb, {"metadata": {"path": notebook_path.parent}})

kfinance/tests/test_fetch.py

@@ -229,6 +229,29 @@ class TestFetchItem(TestCase):
         )
         self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
 
+    def test_fetch_segments(self) -> None:
+        company_id = 21719
+        segment_type = "business"
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}segments/{company_id}/{segment_type}/none/none/none/none/none"
+        self.kfinance_api_client.fetch_segments(company_id=company_id, segment_type=segment_type)
+        self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
+        period_type = PeriodType.quarterly
+        start_year = 2023
+        end_year = 2023
+        start_quarter = 1
+        end_quarter = 4
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}segments/{company_id}/{segment_type}/{period_type.value}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
+        self.kfinance_api_client.fetch_segments(
+            company_id=company_id,
+            segment_type=segment_type,
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        )
+        self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
+
 
 class TestMarketCap:
     @pytest.mark.parametrize(

kfinance/tests/test_objects.py

@@ -75,6 +75,19 @@ MOCK_COMPANY_DB = {
                 }
             }
         },
+        "segments": {
+            "2024": {
+                "Intelligent Cloud": {"Operating Income": 49584000000.0, "Revenue": 105362000000.0},
+                "More Personal Computing": {
+                    "Operating Income": 19309000000.0,
+                    "Revenue": 62032000000.0,
+                },
+                "Productivity and Business Processes": {
+                    "Operating Income": 40540000000.0,
+                    "Revenue": 77728000000.0,
+                },
+            }
+        },
     }
 }
 
@@ -189,6 +202,19 @@ class MockKFinanceApiClient:
             ]
         }
 
+    def fetch_segments(
+        self,
+        company_id,
+        segment_type,
+        period_type,
+        start_year,
+        end_year,
+        start_quarter,
+        end_quarter,
+    ):
+        """Get a segment"""
+        return MOCK_COMPANY_DB[company_id]
+
 
 class TestTradingItem(TestCase):
     def setUp(self):
@@ -309,6 +335,20 @@ class TestCompany(TestCase):
         revenue = self.msft_company.revenue()
         pd.testing.assert_frame_equal(expected_revenue, revenue)
 
+    def test_business_segments(self) -> None:
+        """test business statement"""
+        rows = []
+        for period, segments in MOCK_COMPANY_DB[msft_company_id]["segments"].items():
+            for segment_name, line_items in segments.items():
+                for line_item, value in line_items.items():
+                    rows.append([period, segment_name, line_item, value])
+        expected_segments = pd.DataFrame(
+            rows, columns=["Year", "Segment Name", "Line Item", "Value"]
+        ).replace(np.nan, None)
+
+        business_segment = self.msft_company.business_segments()
+        pd.testing.assert_frame_equal(expected_segments, business_segment)
+
 
 class TestSecurity(TestCase):
     def setUp(self):

kfinance/tests/test_tools.py

@@ -8,7 +8,6 @@ from kfinance.constants import BusinessRelationshipType, Capitalization, Stateme
 from kfinance.kfinance import Client
 from kfinance.tests.conftest import SPGI_COMPANY_ID, SPGI_SECURITY_ID, SPGI_TRADING_ITEM_ID
 from kfinance.tool_calling import (
-    GetCompanyIdFromIdentifier,
     GetEarningsCallDatetimesFromIdentifier,
     GetFinancialLineItemFromIdentifier,
     GetFinancialStatementFromIdentifier,
@@ -18,8 +17,7 @@ from kfinance.tool_calling import (
     GetLatest,
     GetNQuartersAgo,
     GetPricesFromIdentifier,
-    GetSecurityIdFromIdentifier,
-    GetTradingItemIdFromIdentifier,
+    ResolveIdentifier,
 )
 from kfinance.tool_calling.get_business_relationship_from_identifier import (
     GetBusinessRelationshipFromIdentifier,
@@ -107,18 +105,6 @@ class TestGetCapitalizationFromIdentifier:
         assert response == expected_response
 
 
-class TestGetCompanyIdFromIdentifier:
-    def test_get_company_id_from_identifier(self, mock_client: Client):
-        """
-        GIVEN the GetCompanyIdFromIdentifier tool
-        WHEN request the company id for SPGI
-        THEN we get back the SPGI company id
-        """
-        tool = GetCompanyIdFromIdentifier(kfinance_client=mock_client)
-        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
-        assert resp == SPGI_COMPANY_ID
-
-
 class TestGetCusipFromTicker:
     def test_get_cusip_from_ticker(self, requests_mock: Mocker, mock_client: Client):
         """
@@ -380,25 +366,17 @@ class TestPricesFromIdentifier:
         assert response == expected_response
 
 
-class TestGetSecurityIdFromIdentifier:
-    def test_get_security_id_from_identifier(self, mock_client: Client):
+class TestResolveIdentifier:
+    def test_resolve_identifier(self, mock_client: Client):
         """
-        GIVEN the GetSecurityIdFromIdentifier tool
-        WHEN we request the security id for SPGI
-        THEN we get back the SPGI primary security id
+        GIVEN the ResolveIdentifier tool
+        WHEN request to resolve SPGI
+        THEN we get back a dict with the SPGI company id, security id, and trading item id
         """
-        tool = GetSecurityIdFromIdentifier(kfinance_client=mock_client)
+        tool = ResolveIdentifier(kfinance_client=mock_client)
         resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
-        assert resp == SPGI_SECURITY_ID
-
-
-class TestGetTradingItemIdFromIdentifier:
-    def test_get_security_id_from_identifier(self, mock_client: Client):
-        """
-        GIVEN the GetTradingItemIdFromIdentifier tool
-        WHEN we request the trading item id for SPGI
-        THEN we get back the SPGI primary trading item id
-        """
-        tool = GetTradingItemIdFromIdentifier(kfinance_client=mock_client)
-        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
-        assert resp == SPGI_TRADING_ITEM_ID
+        assert resp == {
+            "company_id": SPGI_COMPANY_ID,
+            "security_id": SPGI_SECURITY_ID,
+            "trading_item_id": SPGI_TRADING_ITEM_ID,
+        }

kfinance/tool_calling/__init__.py

@@ -4,7 +4,6 @@ from kfinance.tool_calling.get_business_relationship_from_identifier import (
     GetBusinessRelationshipFromIdentifier,
 )
 from kfinance.tool_calling.get_capitalization_from_identifier import GetCapitalizationFromIdentifier
-from kfinance.tool_calling.get_company_id_from_identifier import GetCompanyIdFromIdentifier
 from kfinance.tool_calling.get_cusip_from_ticker import GetCusipFromTicker
 from kfinance.tool_calling.get_earnings_call_datetimes_from_identifier import (
     GetEarningsCallDatetimesFromIdentifier,
@@ -23,17 +22,13 @@ from kfinance.tool_calling.get_isin_from_ticker import GetIsinFromTicker
 from kfinance.tool_calling.get_latest import GetLatest
 from kfinance.tool_calling.get_n_quarters_ago import GetNQuartersAgo
 from kfinance.tool_calling.get_prices_from_identifier import GetPricesFromIdentifier
-from kfinance.tool_calling.get_security_id_from_identifier import GetSecurityIdFromIdentifier
-from kfinance.tool_calling.get_trading_item_id_from_identifier import GetTradingItemIdFromIdentifier
+from kfinance.tool_calling.resolve_identifier import ResolveIdentifier
 from kfinance.tool_calling.shared_models import KfinanceTool
 
 
 ALL_TOOLS: list[Type[KfinanceTool]] = [
     GetLatest,
     GetNQuartersAgo,
-    GetCompanyIdFromIdentifier,
-    GetSecurityIdFromIdentifier,
-    GetTradingItemIdFromIdentifier,
     GetIsinFromTicker,
     GetCusipFromTicker,
     GetInfoFromIdentifier,
@@ -44,4 +39,5 @@ ALL_TOOLS: list[Type[KfinanceTool]] = [
     GetFinancialStatementFromIdentifier,
     GetFinancialLineItemFromIdentifier,
     GetBusinessRelationshipFromIdentifier,
+    ResolveIdentifier,
 ]

kfinance/tool_calling/get_info_from_identifier.py

@@ -8,7 +8,7 @@ from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdenti
 
 class GetInfoFromIdentifier(KfinanceTool):
     name: str = "get_info_from_identifier"
-    description: str = "Get the information associated with an identifier. Info includes company name, status, type, simple industry, number of employees, founding date, webpage, HQ address, HQ city, HQ zip code, HQ state, HQ country, and HQ country iso code."
+    description: str = "Get the information associated with an identifier. Info includes company name, status, type, simple industry, number of employees (if available), founding date, webpage, HQ address, HQ city, HQ zip code, HQ state, HQ country, and HQ country iso code."
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
     required_permission: Permission | None = None
 

kfinance/tool_calling/resolve_identifier.py

@@ -0,0 +1,18 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.constants import Permission
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class ResolveIdentifier(KfinanceTool):
+    name: str = "resolve_identifier"
+    description: str = (
+        "Get the company_id, security_id, and trading_item_id associated with an identifier."
+    )
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+    required_permission: Permission | None = None
+
+    def _run(self, identifier: str) -> dict[str, int]:
+        return self.kfinance_client.ticker(identifier).id_triple._asdict()

kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.1.2'
-__version_tuple__ = version_tuple = (2, 1, 2)
+__version__ = version = '2.2.2'
+__version_tuple__ = version_tuple = (2, 2, 2)

kfinance/tool_calling/get_company_id_from_identifier.py

@@ -1,16 +0,0 @@
-from typing import Type
-
-from pydantic import BaseModel
-
-from kfinance.constants import Permission
-from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
-
-
-class GetCompanyIdFromIdentifier(KfinanceTool):
-    name: str = "get_company_id_from_identifier"
-    description: str = "Get the company id associated with an identifier."
-    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = None
-
-    def _run(self, identifier: str) -> int:
-        return self.kfinance_client.ticker(identifier).company_id

kfinance/tool_calling/get_security_id_from_identifier.py

@@ -1,16 +0,0 @@
-from typing import Type
-
-from pydantic import BaseModel
-
-from kfinance.constants import Permission
-from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
-
-
-class GetSecurityIdFromIdentifier(KfinanceTool):
-    name: str = "get_security_id_from_identifier"
-    description: str = "Get the security id associated with an identifier."
-    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = None
-
-    def _run(self, identifier: str) -> int:
-        return self.kfinance_client.ticker(identifier).security_id

kfinance/tool_calling/get_trading_item_id_from_identifier.py

@@ -1,16 +0,0 @@
-from typing import Type
-
-from pydantic import BaseModel
-
-from kfinance.constants import Permission
-from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
-
-
-class GetTradingItemIdFromIdentifier(KfinanceTool):
-    name: str = "get_trading_item_id_from_identifier"
-    description: str = "Get the trading item id associated with an identifier."
-    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = None
-
-    def _run(self, identifier: str) -> int:
-        return self.kfinance_client.ticker(identifier).trading_item_id