steindamm 0.7.0__tar.gz

steindamm-0.7.0/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: steindamm
+Version: 0.7.0
+Summary: Python rate limiters backed by Redis
+Keywords: redis,async,sync,rate,limiting,limiters
+Author: Emil Aliyev, Sondre Lillebø Gundersen
+Author-email: Emil Aliyev <ea01052002@gmail.com>, Sondre Lillebø Gundersen <sondrelg@live.no>
+License-Expression: MIT
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: pydantic
+Requires-Dist: redis ; extra == 'redis'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Feuerstein-Org/redis-limiters
+Project-URL: Repository, https://github.com/Feuerstein-Org/redis-limiters
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# Python Redis Limiters
+
+A library which regulates traffic, with respect to concurrency or time.
+It implements sync and async context managers for a [semaphore](#semaphore)- and a [token bucket](#token-bucket)-implementation.
+
+The rate limiters can be distributed using Redis, or run locally in-memory for single-process applications.
+
+**Redis-based limiters** leverage Lua scripts on Redis, each operation is fully atomic.
+Both standalone Redis instances and clusters are supported with sync and async interfaces.
+
+**Local limiters** provide thread-safe (for sync) and asyncio-safe (for async) in-memory rate limiting without requiring Redis.
+
+We currently support Python 3.11, 3.12, and 3.13.
+
+## Features
+
+### Deployment Options
+- **Local (In-Memory)**: Thread-safe and asyncio-safe rate limiting without Redis dependencies
+  - Perfect for single-process applications, testing, and development
+  - Zero external dependencies required
+- **Redis-Based**: Distributed rate limiting using Redis with Lua scripts
+  - Atomic operations for accuracy in distributed systems
+  - Supports both standalone Redis and Redis Cluster
+  - Scales across multiple processes and servers
+
+### Async & Sync Support
+- Full support for both synchronous and asynchronous code
+- Context manager interface (`with` / `async with`)
+
+### Flexibility & Control
+- **Factory Classes**: `SyncTokenBucket` and `AsyncTokenBucket` automatically choose implementation based on connection
+- **Explicit Classes**: Direct access to `SyncRedisTokenBucket`, `AsyncRedisTokenBucket`, `SyncLocalTokenBucket`, `AsyncLocalTokenBucket`
+- **Configurable Token Consumption**: `tokens_to_consume` parameter for variable-cost operations
+- **Customizable Behavior**: Control capacity, refill rates, expiry, max sleep time, and initial state
+
+## Installation
+
+### Basic Installation (Local limiters only)
+```bash
+pip install redis-limiters
+```
+
+### With Redis Support
+```bash
+pip install redis-limiters[redis]
+```
+Or install Redis separately:
+```bash
+pip install redis-limiters redis
+```
+
+## Usage
+
+### Token bucket
+
+The `TokenBucket` classes are useful if you're working with time-based
+rate limits. Say, you are allowed 100 requests per minute, for a given API token.
+
+If the `max_sleep` limit is exceeded, a `MaxSleepExceededError` is raised. Setting `max_sleep` to 0.0 will sleep "endlessly" - this is also the default value. On the other hand `expiry` is how long the token bucket will persist in Redis without any activity (acquires or releases). You might need to adjust both to your requirements.
+
+#### Using Local (In-Memory) Token Bucket
+
+The local token bucket doesn't require Redis and runs entirely in-memory.
+Perfect for single-process applications or testing.
+
+> **Note:** The local token bucket implementation does not currently support expiry of bucket state. Buckets persist in memory for the lifetime of the process. If you are creating buckets dynamically (e.g., one bucket per user or per API key), this could lead to unbounded memory growth. Consider using the Redis-based implementation for applications with dynamic bucket creation, or ensure buckets are reused for the same resources.
+
+**Async version:**
+
+```python
+import asyncio
+
+from httpx import AsyncClient
+
+from redis_limiters import AsyncTokenBucket
+
+# No Redis connection needed - runs in-memory
+limiter = AsyncTokenBucket(
+    name="foo",                # name of the resource you are limiting traffic for
+    capacity=5,                # hold up to 5 tokens (default: 5.0)
+    refill_frequency=1,        # add tokens every second (default: 1.0)
+    refill_amount=1,           # add 1 token when refilling (default: 1.0)
+    initial_tokens=None,       # start with full capacity (default: None, which uses capacity)
+    max_sleep=30,              # raise an error if there are no free tokens for X seconds, 0 never expires (default: 30.0)
+    tokens_to_consume=1,       # consume 1 token per request (default: 1.0)
+)
+
+async def get_foo():
+    async with AsyncClient() as client:
+        async with limiter:
+            await client.get(...)
+
+async def main():
+    await asyncio.gather(
+        get_foo() for i in range(100)
+    )
+```
+
+**Sync version:**
+
+```python
+import requests
+
+from redis_limiters import SyncTokenBucket
+
+limiter = SyncTokenBucket(
+    name="foo",
+    capacity=5,
+    refill_frequency=1,
+    refill_amount=1,
+    tokens_to_consume=1,
+)
+
+def main():
+    with limiter:
+        requests.get(...)
+```
+
+#### Using Redis-Based Token Bucket
+
+For distributed rate limiting across multiple processes or servers,
+use the Redis-based implementation by providing a `connection` parameter.
+
+**Async version:**
+
+```python
+import asyncio
+
+from httpx import AsyncClient
+from redis.asyncio import Redis
+
+from redis_limiters import AsyncTokenBucket
+
+# With Redis connection - distributed across processes/servers
+limiter = AsyncTokenBucket(
+    connection=Redis.from_url("redis://localhost:6379"),  # Add Redis connection for distributed limiting
+    name="foo",
+    capacity=5,
+    refill_frequency=1,
+    refill_amount=1,
+    max_sleep=30,
+    expiry=60,                 # set expiry on Redis keys in seconds (default: 60)
+    tokens_to_consume=1,
+)
+
+async def get_foo():
+    async with AsyncClient() as client:
+        async with limiter:
+            await client.get(...)
+
+async def main():
+    await asyncio.gather(
+        get_foo() for i in range(100)
+    )
+```
+
+**Sync version:**
+
+```python
+import requests
+from redis import Redis
+
+from redis_limiters import SyncTokenBucket
+
+
+limiter = SyncTokenBucket(
+    connection=Redis.from_url("redis://localhost:6379"),
+    name="foo",
+    capacity=5,
+    refill_frequency=1,
+    refill_amount=1,
+    max_sleep=30,
+    expiry=60,
+    tokens_to_consume=1,
+)
+
+def main():
+    with limiter:
+        requests.get(...)
+```
+
+### Semaphore
+
+The semaphore classes are useful when you have concurrency restrictions;
+e.g., say you're allowed 5 active requests at the time for a given API token.
+
+**Note:** Currently, only Redis-based semaphores are available. Local (in-memory) semaphore implementation is planned for a future release.
+
+Beware that the client will block until the Semaphore is acquired,
+or the `max_sleep` limit is exceeded. If the `max_sleep` limit is exceeded, a `MaxSleepExceededError` is raised. Setting `max_sleep` to 0.0 will sleep "endlessly" - default is 30 seconds. On the other hand `expiry` is how long the semaphore will persist in Redis without any activity (acquires or releases). You might need to adjust both to your requirements.
+
+Here's how you might use the async version:
+
+```python
+import asyncio
+
+from httpx import AsyncClient
+from redis.asyncio import Redis
+
+from redis_limiters import AsyncSemaphore
+
+# All properties have defaults except name and connection
+limiter = AsyncSemaphore(
+    connection=Redis.from_url("redis://localhost:6379"),
+    name="foo",    # name of the resource you are limiting traffic for
+    capacity=5,    # allow 5 concurrent requests (default: 5)
+    max_sleep=30,  # raise an error if it takes longer than 30 seconds to acquire the semaphore (default: 30.0)
+    expiry=60,     # set expiry on the semaphore keys in Redis to prevent deadlocks (default: 60)
+)
+
+async def get_foo():
+    async with AsyncClient() as client:
+        async with limiter:
+            await client.get(...)
+
+
+async def main():
+    await asyncio.gather(
+        get_foo() for i in range(100)
+    )
+```
+
+and here is how you might use the sync version:
+
+```python
+import requests
+from redis import Redis
+
+from redis_limiters import SyncSemaphore
+
+
+limiter = SyncSemaphore(
+    connection=Redis.from_url("redis://localhost:6379"),
+    name="foo",
+    capacity=5,
+    max_sleep=30,
+    expiry=60,
+)
+
+def main():
+    with limiter:
+        requests.get(...)
+```
+
+#### Using Explicit Implementation Classes
+
+For explicit control over which implementation to use, import the specific classes:
+
+```python
+# Local implementations
+from redis_limiters import SyncLocalTokenBucket, AsyncLocalTokenBucket
+
+# Redis implementations
+from redis_limiters import SyncRedisTokenBucket, AsyncRedisTokenBucket
+
+# Use directly without factory logic
+local_limiter = SyncLocalTokenBucket(name="api", capacity=10)
+redis_limiter = SyncRedisTokenBucket(connection=redis_conn, name="api", capacity=10)
+```
+
+#### Consuming Multiple Tokens Per Request
+
+You can control how many tokens are consumed per operation using the `tokens_to_consume` parameter.
+This is useful when different operations _on the same api_ have different "costs". Note, how the "name" aka is the same between the limiters which will cause the tokens to be shared.
+
+```python
+from redis_limiters import SyncTokenBucket
+
+# Small requests consume 1 token
+small_limiter = SyncTokenBucket(name="api", capacity=100, tokens_to_consume=1)
+
+# Large requests consume 5 tokens
+large_limiter = SyncTokenBucket(name="api", capacity=100, tokens_to_consume=5)
+
+with small_limiter:
+    make_small_request()  # Consumes 1 token
+
+with large_limiter:
+    make_large_request()  # Consumes 5 tokens
+```
+
+### Using them as a decorator
+
+We don't ship decorators in the package, but if you would
+like to limit the rate at which a whole function is run,
+you can create your own, like this:
+
+```python
+from redis_limiters import AsyncSemaphore
+from redis.asyncio import Redis
+
+# Define a decorator function
+def limit(name, capacity, connection):
+  def middle(f):
+    async def inner(*args, **kwargs):
+      async with AsyncSemaphore(connection=connection, name=name, capacity=capacity):
+        return await f(*args, **kwargs)
+    return inner
+  return middle
+
+# Or for local token buckets (no Redis needed)
+from redis_limiters import AsyncTokenBucket
+
+def rate_limit(name, capacity):
+  def middle(f):
+    async def inner(*args, **kwargs):
+      async with AsyncTokenBucket(name=name, capacity=capacity):
+        return await f(*args, **kwargs)
+    return inner
+  return middle
+
+
+# Then pass the relevant limiter arguments like this
+@limit(name="foo", capacity=5, connection=Redis.from_url("redis://localhost:6379"))
+async def fetch_foo(id: UUID) -> Foo:
+    ...
+
+# Or with local rate limiting
+@rate_limit(name="bar", capacity=10)
+async def fetch_bar(id: UUID) -> Bar:
+    ...
+```
+
+## Contributing
+
+Contributions are very welcome. Here's how to get started:
+
+- Clone the repo
+- Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and [mise](https://mise.jdx.dev/)
+- Run `mise run install` to install dependencies
+  If you prefer not to install mise, check the `mise.toml` file and
+  run the commands manually.
+- Make your code changes, with tests
+- Run tests with `mise run test` or `uv run pytest`
+  Note that you will need to first spin up the redis docker containers. This can be done with `mise run test-setup` (and shut down with `mise run test-teardown`) or the full cycle can be run with `mise run test-full`.
+- Commit your changes and open a PR
+
+## Publishing a new version
+
+To publish a new version:
+
+- Update the package version in the `pyproject.toml`
+- Open [Github releases](https://github.com/Feuerstein-Org/redis-limiters/releases)
+- Press "Draft a new release"
+- Set a tag matching the new version (for example, `v0.8.0`)
+- Set the title matching the tag
+- Add some release notes, explaining what has changed
+- Publish
+
+Once the release is published, our [publish workflow](https://github.com/Feuerstein-Org/redis-limiters/blob/main/.github/workflows/publish.yaml) should be triggered
+to push the new version to PyPI.
+
+## Acknowledgment:
+This project was initially forked from [redis-rate-limiters](https://github.com/otovo/redis-rate-limiters) and was mainly created by Sondre Lillebø Gundersen [link](https://github.com/sondrelg). It was no longer maintained and I since rewrote a lot of stuff as well as added a local version of the limiters and new functionality like the initial amount of tokens or how many tokens to consume at once.