Merge pull request #3 from nklsla/feature/add-report-and-kpi-batch-request

Author: alexwox

README.md

@@ -114,10 +114,12 @@ Comprehensive documentation is available in the `docs` directory:
 - `get_stock_prices()` - Get stock prices for an instrument
 - `get_stock_prices_batch()` - Get stock prices for a batch of instrument
 - `get_reports()` - Get financial reports for an instrument
+- `get_reports_batch()` - Get financial reports for a batch of instrument
 - `get_reports_metadata()` - Get metadata for all financial report values
 - `get_kpi_metadata()` - Get metadata for all KPIs
 - `get_kpi_updated()` - Get last update time for KPIs
 - `get_kpi_history()` - Get one KPIs history for an instrument
+- `get_kpi_history_batch()` - Get one KPIs history for a batch of instrument
 - `get_kpi_summary()` - Get summary of KPIs history for an instrument (Note: Not all kpi's)
 - `get_insider_holdings()` - Get insider holdings for instruments
 - `get_short_positions()` - Get short positions for all instruments

src/borsdata_client/client.py

@@ -1,7 +1,7 @@
 """Borsdata API client implementation."""
 
 from datetime import datetime
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, Iterable, List, Optional
 
 import httpx
 from tenacity import (
@@ -25,6 +25,7 @@
     KpiAllResponse,
     KpiCalcUpdatedResponse,
     KpiMetadata,
+    KpisHistoryArrayResp,
     KpisSummaryResponse,
     KpiSummaryGroup,
     Market,
@@ -33,6 +34,8 @@
     ReportCalendarListResponse,
     ReportMetadata,
     ReportMetadataResponse,
+    ReportsArrayResp,
+    ReportsCombineResp,
     Sector,
     SectorsResponse,
     ShortsListResponse,
@@ -220,22 +223,26 @@ def get_stock_prices(
 
     def get_stock_prices_batch(
         self,
-        instrument_ids: list[int],
+        instrument_ids: Iterable[int],
         from_date: Optional[datetime] = None,
         to_date: Optional[datetime] = None,
     ) -> List[StockPricesArrayRespList]:
         """Get stock prices for multiple instruments, max 50 instruments per call.
 
         Args:
-            instrument_ids: List of instrument IDs
+            instrument_ids: Iterable of instrument IDs
             from_date: Start date for price data
             to_date: End date for price data
 
         Returns:
             List of StockPrice objects
         """
-        assert isinstance(instrument_ids, list), "instrument_ids must be a list"
-        assert len(instrument_ids) <= 50, "Max 50 instrument IDs allowed per request"
+        assert isinstance(
+            instrument_ids, Iterable
+        ), "instrument_ids must be an iterable"
+        assert (
+            len(list(instrument_ids)) <= 50
+        ), "Max 50 instrument IDs allowed per request"
 
         params = {"instList": ",".join(map(str, instrument_ids))}
 
@@ -278,6 +285,56 @@ def get_reports(
         )
         return [Report(**report) for report in response.get("reports", [])]
 
+    def get_reports_batch(
+        self,
+        instrument_ids: Iterable[int],
+        max_year_count: Optional[int] = 10,
+        max_quarter_r12_count: Optional[int] = 10,
+        original_currency: bool = False,
+    ) -> List[ReportsCombineResp]:
+        """Get financial reports for multiple instruments, max 50 instruments per call.
+
+        Args:
+            instrument_ids: Iterable of instrument IDs
+            max_year_count: Maximum number of year reports to return, max 20.
+            max_quarter_r12_count: Maximum number of quarter/R12 reports to return, max 40.
+            original_currency: Whether to return values in original currency
+
+        Returns:
+            List of Report objects
+        """
+        assert isinstance(
+            instrument_ids, Iterable
+        ), "instrument_ids must be an iterable"
+        assert (
+            len(list(instrument_ids)) <= 50
+        ), "Max 50 instrument IDs allowed per request"
+        assert max_quarter_r12_count is None or isinstance(
+            max_quarter_r12_count, int
+        ), "max_quarter_r12_count must be an integer"
+        assert max_year_count <= 20, "max_year_count must be 20 or less"
+        assert max_quarter_r12_count <= 40, "max_quarter_r12_count must be 40 or less"
+
+        params = {"instList": ",".join(map(str, instrument_ids))}
+
+        if max_year_count is not None:
+            assert (
+                isinstance(max_year_count, int) and 0 < max_year_count <= 20
+            ), "max_year_count must be a positive integer"
+            params["maxYearCount"] = str(max_year_count)
+        if max_quarter_r12_count is not None:
+            assert (
+                isinstance(max_quarter_r12_count, int)
+                and 0 < max_quarter_r12_count <= 40
+            ), "max_quarter_r12_count must be a positive integer"
+            params["maxQuarterR12Count"] = str(max_quarter_r12_count)
+
+        params["original"] = "1" if original_currency else "0"
+
+        response = self._get(f"/instruments/reports", params)
+        response_model = ReportsArrayResp(**response)
+        return response_model.report_list
+
     def get_reports_metadata(
         self,
     ) -> List[ReportMetadata]:
@@ -341,8 +398,47 @@ def get_kpi_history(
         )
         return KpiAllResponse(**response)
 
+    def get_kpi_history_batch(
+        self,
+        instrument_ids: Iterable[int],
+        kpi_id: int,
+        report_type: str,
+        price_type: str = "mean",
+        max_count: Optional[int] = None,
+    ) -> List[KpiAllResponse]:
+        """Get KPI history for multiple instruments, max 50 instruments per call.
+
+        Args:
+            instrument_ids: IDs of the instruments
+            kpi_id: ID of the KPI
+            report_type: Type of report ('year', 'r12', 'quarter')
+            price_type: Type of price calculation
+            max_count: Maximum number of results to return, 10 by default. report_type 'year' can return max 20, 'r12' and 'quarter' can return max 40.
+
+        Returns:
+            List of KPI responses
+        """
+
+        assert isinstance(
+            instrument_ids, Iterable
+        ), "instrument_ids must be an iterable"
+        assert (
+            len(list(instrument_ids)) <= 50
+        ), "Max 50 instrument IDs allowed per request"
+
+        params = {"instList": ",".join(map(str, instrument_ids))}
+        if max_count:
+            params["maxCount"] = str(max_count)
+
+        response = self._get(
+            f"/instruments/kpis/{kpi_id}/{report_type}/{price_type}/history",
+            params,
+        )
+
+        return KpisHistoryArrayResp(**response)
+
     def get_kpi_summary(
-        self, instrument_id: str, report_type: str, max_count: Optional[int] = None
+        self, instrument_id: int, report_type: str, max_count: Optional[int] = None
     ) -> List[KpiSummaryGroup]:
         """Get all KPI history for an instrument.
 
@@ -364,7 +460,7 @@ def get_kpi_summary(
         return KpisSummaryResponse(**response).kpis or []
 
     def get_insider_holdings(
-        self, instrument_ids: List[int]
+        self, instrument_ids: Iterable[int]
     ) -> List[InsiderListResponse]:
         """Get insider holdings for specified instruments.
 
@@ -387,7 +483,7 @@ def get_short_positions(self) -> List[ShortsListResponse]:
         response = self._get("/holdings/shorts")
         return ShortsListResponse(**response).list or []
 
-    def get_buybacks(self, instrument_ids: List[int]) -> List[BuybackListResponse]:
+    def get_buybacks(self, instrument_ids: Iterable[int]) -> List[BuybackListResponse]:
         """Get buyback data for specified instruments.
 
         Args:
@@ -401,12 +497,12 @@ def get_buybacks(self, instrument_ids: List[int]) -> List[BuybackListResponse]:
         return BuybackListResponse(**response).list or []
 
     def get_instrument_descriptions(
-        self, instrument_ids: List[int]
+        self, instrument_ids: Iterable[int]
     ) -> List[InstrumentDescriptionListResponse]:
         """Get descriptions for specified instruments.
 
         Args:
-            instrument_ids: List of instrument IDs to get descriptions for
+            instrument_ids: Iterable of instrument IDs to get descriptions for
 
         Returns:
             List of instrument description responses
@@ -416,12 +512,12 @@ def get_instrument_descriptions(
         return InstrumentDescriptionListResponse(**response).list or []
 
     def get_report_calendar(
-        self, instrument_ids: List[int]
+        self, instrument_ids: Iterable[int]
     ) -> List[ReportCalendarListResponse]:
         """Get report calendar for specified instruments.
 
         Args:
-            instrument_ids: List of instrument IDs to get calendar for
+            instrument_ids: Iterable of instrument IDs to get calendar for
 
         Returns:
             List of report calendar responses
@@ -431,12 +527,12 @@ def get_report_calendar(
         return ReportCalendarListResponse(**response).list or []
 
     def get_dividend_calendar(
-        self, instrument_ids: List[int]
+        self, instrument_ids: Iterable[int]
     ) -> List[DividendCalendarListResponse]:
         """Get dividend calendar for specified instruments.
 
         Args:
-            instrument_ids: List of instrument IDs to get calendar for
+            instrument_ids: Iterable of instrument IDs to get calendar for
 
         Returns:
             List of dividend calendar responses

src/borsdata_client/models.py

@@ -101,6 +101,40 @@ class KpisSummaryResponse(BaseModel):
     kpis: Optional[List[KpiSummaryGroup]]
 
 
+class KpiHistory(BaseModel):
+    y: int = Field(description="Year")
+    p: int = Field(description="Period")
+    v: Optional[float] = Field(None, description="Value (nullable)")
+
+    @property
+    def year(self) -> int:
+        return self.y
+
+    @property
+    def period(self) -> int:
+        return self.p
+
+    @property
+    def value(self) -> Optional[float]:
+        return self.v
+
+
+class KpisHistoryComp(BaseModel):
+    instrument: int
+    kpi_id: Optional[int] = Field(None, alias="kpiId", description="KPI ID")
+    error: Optional[str] = Field(None, description="Optional error message")
+    values: Optional[List[KpiHistory]] = Field(
+        None, description="List of KPI history values"
+    )
+
+
+class KpisHistoryArrayResp(BaseModel):
+    kpi_id: int = Field(alias="kpiId")
+    report_time: Optional[str] = Field(None, alias="reportTime")
+    price_value: Optional[str] = Field(None, alias="priceValue")
+    kpis_list: Optional[List[KpisHistoryComp]] = Field(None, alias="kpisList")
+
+
 class Report(BaseModel):
     """Financial report model."""
 
@@ -155,6 +189,18 @@ class Report(BaseModel):
     report_date: Optional[datetime] = Field(None, alias="report_Date")
 
 
+class ReportsCombineResp(BaseModel):
+    instrument: int
+    error: Optional[str] = None
+    reports_year: Optional[List[Report]] = Field(None, alias="reportsYear")
+    reports_quarter: Optional[List[Report]] = Field(None, alias="reportsQuarter")
+    reports_r12: Optional[List[Report]] = Field(None, alias="reportsR12")
+
+
+class ReportsArrayResp(BaseModel):
+    report_list: Optional[List[ReportsCombineResp]] = Field(None, alias="reportList")
+
+
 class ReportMetadata(BaseModel):
     report_property: Optional[str] = Field(None, alias="reportPropery")
     name_sv: Optional[str] = Field(None, alias="nameSv")

tests/test_endpoints.py

@@ -24,6 +24,7 @@
     Market,
     Report,
     ReportCalendarResponse,
+    ReportsCombineResp,
     ShortsResponse,
     StockPrice,
     StockPriceLastValue,
@@ -395,6 +396,73 @@ def test_get_reports(mock_client):
     assert reports[0].earnings_per_share == 2
 
 
+# Test for get_report_batch
+def test_get_report_batch(mock_client):
+    """Test the get_report_batch method."""
+    # Create mock response
+    rep_data = {
+        "year": 2020,
+        "period": 1,
+        "revenues": 1000,
+        "gross_Income": 800.0,
+        "operating_Income": 600.0,
+        "profit_Before_Tax": 500.0,
+        "profit_To_Equity_Holders": 400.0,
+        "earnings_Per_Share": 2.0,
+        "number_Of_Shares": 200.0,
+        "dividend": 1.0,
+        "intangible_Assets": 300.0,
+        "tangible_Assets": 400.0,
+        "financial_Assets": 500.0,
+        "non_Current_Assets": 1200.0,
+        "cash_And_Equivalents": 200.0,
+        "current_Assets": 1500.0,
+        "total_Assets": 3000.0,
+        "total_Equity": 1800.0,
+        "non_Current_Liabilities": 700.0,
+        "current_Liabilities": 500.0,
+        "total_Liabilities_And_Equity": 3000.0,
+        "net_Debt": 100.0,
+        "cash_Flow_From_Operating_Activities": 600.0,
+        "cash_Flow_From_Investing_Activities": -200.0,
+        "cash_Flow_From_Financing_Activities": -100.0,
+        "cash_Flow_For_The_Year": 300.0,
+        "free_Cash_Flow": 400.0,
+        "stock_Price_Average": 50.0,
+        "stock_Price_High": 60.0,
+        "stock_Price_Low": 40.0,
+        "report_Start_Date": "2020-01-01T00:00:00",
+        "report_End_Date": "2020-12-31T00:00:00",
+        "broken_Fiscal_Year": False,
+        "currency": "USD",
+    }
+    create_mock_response(
+        "instruments/reports",
+        {
+            "reportList": [
+                {
+                    "instrument": 1,
+                    "error": "No error",
+                    "reportsYear": [rep_data],
+                    "reportsQuarter": [rep_data],
+                    "reportsR12": [rep_data],
+                }
+            ]
+        },
+    )
+    # Call the method
+    reports = mock_client.get_reports_batch(instrument_ids=[1])
+
+    # Verify the result
+    assert len(reports) == 1
+    assert isinstance(reports[0], ReportsCombineResp)
+    assert isinstance(reports[0].reports_year[0], Report)
+    assert reports[0].instrument == 1
+    assert reports[0].reports_year[0].year == 2020
+    assert reports[0].reports_quarter[0].revenues == 1000
+    assert reports[0].reports_r12[0].earnings_per_share == 2
+
+
 # Test for get_kpi_metadata
 def test_get_kpi_metadata(mock_client):
     """Test the get_kpi_metadata method."""