Skip to content

docs: add fixed window, sliding window log, sliding window counter, and leaky bucket algorithms to redis-py rate limiter page - #3788

Merged
andy-stark-redis merged 2 commits into
redis:mainfrom
YashwinReddy29:feat/rate-limiting-python-tutorial
Aug 13, 2026
Merged

docs: add fixed window, sliding window log, sliding window counter, and leaky bucket algorithms to redis-py rate limiter page#3788
andy-stark-redis merged 2 commits into
redis:mainfrom
YashwinReddy29:feat/rate-limiting-python-tutorial

Conversation

@YashwinReddy29

@YashwinReddy29 YashwinReddy29 commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

What this adds

Four additional rate limiting algorithm implementations in Python to
the existing redis-py rate limiter page, which currently covers only
the token bucket algorithm.

The other language pages (nodejs, go, java, rust, dotnet, php) also
only cover token bucket. This PR fills that gap for Python.

What's included

  • Algorithm comparison table (token bucket, fixed window, sliding
    window log, sliding window counter, leaky bucket)
  • Fixed window counter — STRING + Lua, one EVAL round trip
  • Sliding window log — SORTED SET + Lua, exact rolling window
  • Sliding window counter — STRING x2 + Lua, near-exact with hash
    tags for Redis Cluster compatibility
  • Leaky bucket (policing mode) — HASH + Lua, strict no-burst

Clock drift fix

All new scripts derive now from redis.call('TIME') inside the
Lua script rather than time.time() in the caller. This eliminates
clock drift when the limiter runs across multiple application servers.

Full implementation

A complete runnable implementation with demo script is at:
https://github.com/YashwinReddy29/redis-rate-limiting-python

Context

This contribution was suggested by @petyaslavova during review of
redis-py PRs #4248 and #4257, where she pointed to redis/docs as
the right home for application-level rate limiting patterns in Python.


Note

Low Risk
Documentation-only changes with illustrative Lua/Python snippets; no runtime, auth, or infrastructure behavior is modified.

Overview
Expands the redis-py rate limiter doc beyond token bucket with an algorithm comparison table and four new Lua + Python patterns: fixed window counter, sliding window log, sliding window counter (with hash tags for Cluster), and leaky bucket (policing).

All new examples use redis.call('TIME') in Lua instead of caller-side clocks, and each section notes trade-offs (boundary bursts, memory, estimate accuracy, immediate rejects). Learn more adds a link to the community redis-rate-limiting-python repo.

Reviewed by Cursor Bugbot for commit 5a7e0d2. Bugbot is set up for automated code reviews on this repo. Configure here.

Signed-off-by: Yashwin Reddy Lakkireddy <yashwinlakkireddy@gmail.com>
@CLAassistant

CLAassistant commented Aug 11, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

Reviewed by Cursor Bugbot for commit 3e816db. Configure here.

Comment thread content/develop/use-cases/rate-limiter/redis-py/_index.md Outdated
@dwdougherty dwdougherty added the clients Client library docs label Aug 11, 2026

@andy-stark-redis andy-stark-redis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@YashwinReddy29 Thanks for your contribution!

I've made a few suggestions and there is at least one comment from the Bugbot, which I think you should be able to see now. Please comment on the PR if there is anything you'd like to discuss further.

Once we're happy with this and it's merged, I'll add corresponding examples for the other client languages. This will be a great addition to the docs :-)

Comment thread content/develop/use-cases/rate-limiter/redis-py/_index.md Outdated
Comment thread content/develop/use-cases/rate-limiter/redis-py/_index.md Outdated
Comment thread content/develop/use-cases/rate-limiter/redis-py/_index.md Outdated
Comment thread content/develop/use-cases/rate-limiter/redis-py/_index.md Outdated
Comment thread content/develop/use-cases/rate-limiter/redis-py/_index.md Outdated
Comment thread content/develop/use-cases/rate-limiter/redis-py/_index.md Outdated
- Fix clock-skew bug in sliding window counter: derive window number
  and elapsed fraction from redis.call('TIME') inside the Lua script
  instead of the application server's local clock, eliminating
  under-enforcement when app servers have skewed clocks
- Rename 'Additional rate limiting algorithms' to 'Alternative rate
  limiting algorithms' and fold the comparison table into the intro
  with anchor links to each section
- Remove the now-redundant standalone 'Algorithm comparison' table
- Rename 'Leaky bucket (policing mode)' to 'Leaky bucket (policing)'
  to match the table
- Remove the redundant 'Choosing an algorithm' list and move 'Learn
  more' to the end of the page, including the redis-rate-limiting-python
  repo link as a proper list item
@YashwinReddy29

Copy link
Copy Markdown
Contributor Author

Thanks for the review! Pushed a commit addressing all the suggestions: fixed the clock-skew issue Bugbot flagged (moved the window/elapsed calculation into the Lua script via redis.call('TIME'), tested locally against real Redis to confirm the fix — 5/5 requests allowed within a window and correct roll-over across window boundaries), renamed the section and folded the comparison table into the intro as suggested, removed the duplicate list, and moved Learn more to the end with the repo link included. Let me know if anything else needs adjusting.

@andy-stark-redis andy-stark-redis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@andy-stark-redis

Copy link
Copy Markdown
Contributor

@YashwinReddy29 Excellent - I'll merge this and open a ticket to add the corresponding versions for the other client languages (I can't give a timescale for finishing this, but it should hopefully land quite soon). Thanks once again for your contribution!

@andy-stark-redis
andy-stark-redis merged commit 017e4f3 into redis:main Aug 13, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

clients Client library docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants