Skip to content
Back to top
View this page

# pyrate_limiter.abstracts package

class pyrate_limiter.abstracts.AbstractBucket

  Bases: `ABC`

  Base bucket interface Assumption: len(rates) always > 0 TODO: allow empty rates

  close()

    Release any resources held by the bucket.

    Subclasses may override this method to perform any necessary cleanup (e.g., closing files, network connections, or releasing locks) when the bucket is no longer needed.

    Return type:

      `None`

  abstractmethod count()

    Count number of items in the bucket

    Return type:

      `int` | `Awaitable`[`int`]

  failing_rate = None
  abstractmethod flush()

    Flush the whole bucket - Must remove failing-rate after flushing

    Return type:

      `None` | `Awaitable`[`None`]

  is_async = None
  abstractmethod leak(current_timestamp=None)

    leaking bucket - removing items that are outdated

    Return type:

      `int` | `Awaitable`[`int`]

  limiter_lock()

    An additional lock to be used by Limiter in-front of the thread lock. Intended for multiprocessing environments where a thread lock is insufficient.

    Return type:

      `object` | `None`

  now()

    Retrieve current timestamp from the clock backend.

  abstractmethod peek(index)

    Peek at the rate-item at a specific index in latest-to-earliest order NOTE: The reason we cannot peek from the start of the queue(earliest-to-latest) is we can’t really tell how many outdated items are still in the queue

    Return type:

      `RateItem` | `None` | `Awaitable`[`RateItem` | `None`]

  abstractmethod put(item)

    Put an item (typically the current time) in the bucket return true if successful, otherwise false

    Return type:

      `bool` | `Awaitable`[`bool`]

  property rates
  waiting(item)

    Calculate time until bucket become availabe to consume an item again

    Return type:

      `int` | `Awaitable`[`int`]

class pyrate_limiter.abstracts.BucketAsyncWrapper(bucket)

  Bases: `AbstractBucket`

  BucketAsyncWrapper is a wrapping over any bucket that turns a async/synchronous bucket into an async one

  async count()

    Count number of items in the bucket

  property failing_rate

    The type of the None singleton.

  async flush()

    Flush the whole bucket - Must remove failing-rate after flushing

    Return type:

      `None`

  is_async = True
  async leak(current_timestamp=None)

    leaking bucket - removing items that are outdated

    Return type:

      `int`

  now()

    Retrieve current timestamp from the clock backend.

    Return type:

      `int`

  async peek(index)

    Peek at the rate-item at a specific index in latest-to-earliest order NOTE: The reason we cannot peek from the start of the queue(earliest-to-latest) is we can’t really tell how many outdated items are still in the queue

    Return type:

      `RateItem` | `None`

  async put(item)

    Put an item (typically the current time) in the bucket return true if successful, otherwise false

  property rates
  async waiting(item)

    Calculate time until bucket become availabe to consume an item again

    Return type:

      `int`

class pyrate_limiter.abstracts.BucketFactory

  Bases: `ABC`

  Asbtract BucketFactory class. It is reserved for user to implement/override this class with his own bucket-routing/creating logic

  close()
    Return type:

      `None`

  create(bucket_class, *args, **kwargs)

    Creating a bucket dynamically

    Return type:

      `AbstractBucket`

  dispose(bucket)

    Delete a bucket from the factory

    Return type:

      `bool`

  abstractmethod get(item)

    Get the corresponding bucket to this item

    Return type:

      `AbstractBucket` | `Awaitable`[`AbstractBucket`]

  get_buckets()

    Iterator over all buckets in the factory

    Return type:

      `List`[`AbstractBucket`]

  property leak_interval

    Retrieve leak-interval from inner Leaker task

  schedule_leak(new_bucket)

    Schedule all the buckets’ leak, reset bucket’s failing rate

    Return type:

      `None`

  abstractmethod wrap_item(name, weight=1)

    Add the current timestamp to the receiving item using any clock backend - Turn it into a RateItem - Can return either a coroutine or a RateItem instance

    Return type:

      `RateItem` | `Awaitable`[`RateItem`]

class pyrate_limiter.abstracts.Duration(*values)

  Bases: `Enum`

  Interval helper class

  DAY = 86400000
  HOUR = 3600000
  MINUTE = 60000
  SECOND = 1000
  WEEK = 604800000
  static readable(value)
    Return type:

      `str`

class pyrate_limiter.abstracts.Rate(limit, interval)

  Bases: `object`

  Rate definition.

  Parameters:

    - limit (`int`) – Number of requests allowed within `interval`

    - interval (`int` | `Duration`) – Time interval, in miliseconds

  interval
  limit

class pyrate_limiter.abstracts.RateItem(name, timestamp, weight=1)

  Bases: `object`

  RateItem is a wrapper for bucket to work with

  name
  timestamp
  weight

## Submodules

- pyrate_limiter.abstracts.algorithm module
  - `Algorithm`
    - `Algorithm.admit()`
    - `Algorithm.leak_bound()`
  - `Decision`
    - `Decision.allowed`
    - `Decision.failing_rate`
  - `SlidingWindowLog`
    - `SlidingWindowLog.admit()`
    - `SlidingWindowLog.leak_bound()`
- pyrate_limiter.abstracts.bucket module
  - `AbstractBucket`
    - `AbstractBucket.close()`
    - `AbstractBucket.count()`
    - `AbstractBucket.failing_rate`
    - `AbstractBucket.flush()`
    - `AbstractBucket.is_async`
    - `AbstractBucket.leak()`
    - `AbstractBucket.limiter_lock()`
    - `AbstractBucket.now()`
    - `AbstractBucket.peek()`
    - `AbstractBucket.put()`
    - `AbstractBucket.rates`
    - `AbstractBucket.waiting()`
  - `BucketFactory`
    - `BucketFactory.close()`
    - `BucketFactory.create()`
    - `BucketFactory.dispose()`
    - `BucketFactory.get()`
    - `BucketFactory.get_buckets()`
    - `BucketFactory.leak_interval`
    - `BucketFactory.schedule_leak()`
    - `BucketFactory.wrap_item()`
  - `Leaker`
    - `Leaker.aio_leak_task`
    - `Leaker.async_buckets`
    - `Leaker.close()`
    - `Leaker.deregister()`
    - `Leaker.is_alive()`
    - `Leaker.leak_async()`
    - `Leaker.leak_interval`
    - `Leaker.name`
    - `Leaker.register()`
    - `Leaker.start()`
    - `Leaker.sync_buckets`
- pyrate_limiter.abstracts.rate module
  - `Duration`
    - `Duration.DAY`
    - `Duration.HOUR`
    - `Duration.MINUTE`
    - `Duration.SECOND`
    - `Duration.WEEK`
    - `Duration.readable()`
  - `Rate`
    - `Rate.interval`
    - `Rate.limit`
  - `RateItem`
    - `RateItem.name`
    - `RateItem.timestamp`
    - `RateItem.weight`
- pyrate_limiter.abstracts.wrappers module
  - `BucketAsyncWrapper`
    - `BucketAsyncWrapper.count()`
    - `BucketAsyncWrapper.failing_rate`
    - `BucketAsyncWrapper.flush()`
    - `BucketAsyncWrapper.is_async`
    - `BucketAsyncWrapper.leak()`
    - `BucketAsyncWrapper.now()`
    - `BucketAsyncWrapper.peek()`
    - `BucketAsyncWrapper.put()`
    - `BucketAsyncWrapper.rates`
    - `BucketAsyncWrapper.waiting()`