ds_protocol_http_py_lib.utils.http.token_bucket
===============================================

.. py:module:: ds_protocol_http_py_lib.utils.http.token_bucket

.. autoapi-nested-parse::

   **File:** ``token_bucket.py``
   **Region:** ``ds_protocol_http_py_lib/utils/http/token_bucket``

   Token Bucket Rate Limiter

   This module implements a cooperative token bucket algorithm for rate limiting HTTP requests.
   A token bucket maintains a reservoir of tokens that are consumed when requests are made.
   Tokens are replenished at a constant rate (tokens per second), providing smooth rate limiting
   that allows burst traffic while maintaining an overall rate cap.

   Key features:
   - Thread-safe using threading.Lock
   - Configurable requests per second (RPS) rate
   - Adjustable capacity for burst handling
   - Uses threading.Lock for thread-safe operations
   - Global RPS cap across all concurrent operations

   .. rubric:: Example

   >>> limiter = TokenBucket(rps=10.0, capacity=20)
   >>> limiter.acquire()
   >>> # Make your HTTP request here



Attributes
----------

.. autoapisummary::

   ds_protocol_http_py_lib.utils.http.token_bucket.logger


Classes
-------

.. autoapisummary::

   ds_protocol_http_py_lib.utils.http.token_bucket.TokenBucket


Module Contents
---------------

.. py:data:: logger

.. py:class:: TokenBucket(rps: float = 10.0, capacity: int = 20)

   Token Bucket Rate Limiter

   Implements the classic token bucket algorithm for controlling request rates in threading environments.
   Each request consumes one token from the bucket. If no tokens are available, the request waits
   until tokens are replenished based on the configured rate.

   The bucket starts full and refills continuously at the specified RPS rate. This allows for
   burst traffic (up to the bucket capacity) while maintaining the overall rate limit.

   :param rps: Target requests per second rate. Determines token refill rate.
   :param capacity: Maximum number of tokens the bucket can hold. Defaults to 2x RPS.
   :return: None

   .. rubric:: Example

   # Limit to 10 requests per second with burst capacity of 20
   limiter = TokenBucket(rps=10.0, capacity=20)

   # Acquire permission for a request
   limiter.acquire()
   # Make your HTTP request here


   .. py:attribute:: rps


   .. py:attribute:: capacity
      :value: 20



   .. py:attribute:: tokens


   .. py:attribute:: last


   .. py:attribute:: _lock


   .. py:method:: acquire() -> None

      Acquire a token from the bucket, waiting if necessary.
      :return: None



   .. py:method:: available() -> float

      Return the current available token count *without mutating* internal state.

      This computes how many tokens would be available if we refilled based on
      elapsed time, but it does not update `tokens` or `last`.