#152 Add rate limiting to API requests with new RateLimiter class

Introduced a `RateLimiter` class to enforce method-level request rate limits as per Tinkoff API guidelines. Updated the core API request flow to utilize the rate limiter for both client-side and server-enforced rate limit handling. Also added predefined `TKS_METHOD_LIMITS` for rate configurations.

Author: Tim55667757

tksbrokerapi/TKSBrokerAPI.py

@@ -70,7 +70,7 @@
 7. Profit!
 """
 
-# Copyright (c) 2022 Gilmillin Timur Mansurovich
+# Copyright (c) 2025 Gilmillin Timur Mansurovich
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -91,8 +91,10 @@
 import re
 import json
 import traceback as tb
-from time import sleep
+import threading
+from time import sleep, monotonic
 from argparse import ArgumentParser
+from collections import defaultdict
 from importlib.metadata import version
 from multiprocessing import cpu_count
 
@@ -139,6 +141,112 @@
 CPU_USAGES = CPU_COUNT - 1 if CPU_COUNT > 1 else 1  # how many CPUs will be used for parallel calculations
 
 
+class RateLimiter:
+    def __init__(self, methodLimits: dict[str, int]):
+        """
+        Initialize RateLimiter with given method limits (requests per minute).
+
+        :param methodLimits: dict[str, int] with per-method RPM limits.
+        """
+        self.methodLimits = methodLimits
+        """Per-method RPM limits."""
+
+        self.counters = defaultdict(int)
+        """Number of requests sent per method in the current window."""
+
+        self.timestamps = defaultdict(float)
+        """Timestamp (monotonic) of the start of current window per method."""
+
+        self.events = defaultdict(threading.Event)
+        """Synchronization event for each method to coordinate waiting."""
+
+        self.moreDebug = False
+        """Enables more debug information in this class. `False` by default."""
+
+    def CheckRateLimit(self, methodName: str) -> None:
+        """
+        Check if the request for the method can proceed. Wait if needed.
+
+        :param methodName: str with the method name.
+        """
+        now = monotonic()
+        limit = self.methodLimits.get(methodName, self.methodLimits["default"])
+
+        if self.timestamps[methodName] == 0.0:
+            self.timestamps[methodName] = now
+            elapsed = 0.0
+
+        else:
+            elapsed = now - self.timestamps[methodName]
+
+        if self.moreDebug:
+            uLogger.debug(f"[RateLimiter] Checking method='{methodName}': counter={self.counters[methodName]}, elapsed={elapsed:.2f}s, limit={limit}")
+
+        # Reset counters if the time window has passed:
+        if elapsed > 60.0:
+            if self.moreDebug:
+                uLogger.debug(f"[RateLimiter] Resetting window for method='{methodName}' after {elapsed:.2f}s.")
+
+            self.counters[methodName] = 0
+            self.timestamps[methodName] = now
+            self.events[methodName].set()
+            self.events[methodName].clear()
+
+        # If the limit is exceeded, wait cooperatively:
+        if self.counters[methodName] >= limit:
+            event = self.events[methodName]
+
+            if event.is_set():
+                if self.moreDebug:
+                    uLogger.debug(f"[RateLimiter] Method='{methodName}' is waiting on event from another thread...")
+
+                event.wait()
+
+            else:
+                waitTime = max(0.0, 60.0 - elapsed)
+
+                uLogger.debug(f"[RateLimiter] Limit reached for method='{methodName}'. Waiting {waitTime:.2f}s...")
+
+                sleep(waitTime)
+
+                self.counters[methodName] = 0
+                self.timestamps[methodName] = monotonic()
+
+                event.set()
+                event.clear()
+
+        self.counters[methodName] += 1
+
+    def HandleServerRateLimit(self, methodName: str, waitTime: int) -> None:
+        """
+        Handle server-enforced rate limit using cooperative waiting.
+
+        :param methodName: str with the method name.
+        :param waitTime: int time in seconds to wait before retrying the request.
+        """
+        uLogger.debug(f"[RateLimiter] Server-enforced limit for method='{methodName}', waitTime={waitTime}s.")
+
+        event = self.events[methodName]
+
+        if event.is_set():
+            if self.moreDebug:
+                uLogger.debug(f"[RateLimiter] Method='{methodName}' waiting on event triggered by server limit...")
+
+            event.wait()
+
+        else:
+            if self.moreDebug:
+                uLogger.debug(f"[RateLimiter] Sleeping {waitTime}s due to server rate limit for method='{methodName}'.")
+
+            sleep(waitTime)
+
+            self.counters[methodName] = 0
+            self.timestamps[methodName] = monotonic()
+
+            event.set()
+            event.clear()
+
+
 class TinkoffBrokerServer:
     """
     This class implements methods to work with Tinkoff broker server.
@@ -251,7 +359,7 @@ def __init__(self, token: str, accountId: str = None, useCache: bool = True, def
         """
 
         self.pause = 3
-        """Sleep time in seconds between retries, in all network requests 5 seconds by default.
+        """Sleep time in seconds between retries, in all network requests 3 seconds by default.
 
         See also: `SendAPIRequest()`.
         """
@@ -448,6 +556,9 @@ def __init__(self, token: str, accountId: str = None, useCache: bool = True, def
         See also: `LoadHistory()`, `ShowHistoryChart()` and the PriceGenerator project: https://github.com/Tim55667757/PriceGenerator
         """
 
+        self.rateLimiter = RateLimiter(methodLimits=TKS_METHOD_LIMITS)  # init RateLimiter object to work with `TKS_METHOD_LIMITS`
+        """RateLimiter object to work with given method limits (requests per minute) from `TKS_METHOD_LIMITS`."""
+
     @property
     def tag(self) -> str:
         """Identification TKSBrokerAPI tag in log messages to simplify debugging when platform instances runs in parallel mode. Default: `""` (empty string)."""
@@ -571,6 +682,9 @@ def SendAPIRequest(self, url: str, reqType: str = "GET") -> dict:
             currentPause = self.pause  # initial pause
 
             while not response and counter <= self.retry:
+                methodName = url.split("/")[-1].split("?")[0]  # method name in `TKS_METHOD_LIMITS`
+                self.rateLimiter.CheckRateLimit(methodName)  # checking rate limits...
+
                 try:
                     # try to send REST-request:
                     if reqType == "GET":
@@ -616,9 +730,7 @@ def SendAPIRequest(self, url: str, reqType: str = "GET") -> dict:
                 if response and response.headers and response.headers.get("x-ratelimit-remaining") == "0":
                     rateLimitWait = int(response.headers["x-ratelimit-reset"])
 
-                    uLogger.debug("Rate limit exceeded. Waiting {} sec. for reset rate limit and then repeat again...".format(rateLimitWait))
-
-                    sleep(rateLimitWait)
+                    self.rateLimiter.HandleServerRateLimit(methodName, rateLimitWait)  # wait if broker returns rate limit
 
                 # handling 4xx client errors: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
                 if response and 400 <= response.status_code < 500:
@@ -5117,7 +5229,8 @@ def Main(**kwargs):
             # --- set some options:
 
             if args.more:
-                trader.moreDebug = True
+                trader.moreDebug = True  # enables more debug information in class TinkoffBrokerServer class
+                trader.rateLimiter.moreDebug = True  # enables more debug information in RateLimiter class
                 uLogger.warning("More debug mode is enabled! See network requests, responses and its headers in the full log or run TKSBrokerAPI platform with the `--verbosity 10` to show theres in console.")
 
             if args.html:

tksbrokerapi/TKSEnums.py

@@ -17,7 +17,7 @@
 - **Open account for trading:** https://tinkoff.ru/sl/AaX1Et1omnH
 """
 
-# Copyright (c) 2022 Gilmillin Timur Mansurovich
+# Copyright (c) 2025 Gilmillin Timur Mansurovich
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -32,6 +32,56 @@
 # limitations under the License.
 
 
+TKS_METHOD_LIMITS = {
+    # Default
+    "default": 50,  # Default fallback for unknown or uncategorized endpoints
+
+    # Orders
+    "PostOrder": 50,  # Place order (POST /orders)
+    "CancelOrder": 50,  # Cancel order (POST /orders/cancel)
+    "GetOrders": 50,  # Get active orders (GET /orders)
+
+    # Stop-orders
+    "PostStopOrder": 25,  # Place stop-order (POST /stop-orders)
+    "CancelStopOrder": 25,  # Cancel stop-order (POST /stop-orders/cancel)
+    "GetStopOrders": 25,  # Get stop-orders (GET /stop-orders)
+
+    # Portfolio & positions
+    "GetPortfolio": 100,  # Get portfolio (GET /operations/portfolio)
+    "GetPositions": 100,  # Get positions (GET /operations/positions)
+    "GetWithdrawLimits": 100,  # Get withdrawal limits (GET /operations/withdraw-limits)
+
+    # Market data
+    "GetCandles": 150,  # Get candles (GET /market/candles)
+    "GetOrderBook": 150,  # Get orderbook (GET /market/orderbook)
+    "GetLastPrices": 150,  # Get last prices (GET /market/last-prices)
+    "GetTradingStatus": 150,  # Get trading status (GET /market/trading-status)
+    "GetClosePrices": 150,  # Get close prices (GET /market/close-prices)
+
+    # History zip-archive
+    "getHistory": 30,  # Get history (GET history-data) https://tinkoff.github.io/investAPI/get_history/
+
+    # Instruments
+    "SearchByFigi": 100,  # Search by FIGI (GET /market/search/by-figi)
+    "SearchByTicker": 100,  # Search by ticker (GET /market/search/by-ticker)
+    "GetInstrumentBy": 100,  # Generic search endpoint (GET /market/search)
+
+    # Operations
+    "GetOperations": 100,  # Get operations (GET /operations)
+
+    # Users
+    "GetAccounts": 50,  # Get accounts (GET /user/accounts)
+    "GetInfo": 50,  # Get user info (GET /user/info)
+    "GetMarginAttributes": 50,  # Margin info (GET /user/margin-attributes)
+    "GetUserTariff": 50,  # Get tariff info (GET /user/tariff)
+
+    # Reports
+    "GetBrokerReport": 100,  # Get broker report (POST /operations/broker-report)
+    "GetDividendsForeignIssuer": 100  # Dividends from foreign issuers (POST /operations/dividends/foreign)
+}
+"""Unary method limits (per minute) from Tinkoff API: https://tinkoff.github.io/investAPI/limits/"""
+
+
 TKS_DATE_TIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
 """Date and time string format used by Tinkoff Open API. Default: `"%Y-%m-%dT%H:%M:%SZ"`."""