Metadata-Version: 2.4
Name: edging
Version: 0.1.0
Summary: Rate limiting that approaches but never exceeds a threshold.
Project-URL: Homepage, https://github.com/coldbricks/edging
Project-URL: Repository, https://github.com/coldbricks/edging
Project-URL: Issues, https://github.com/coldbricks/edging/issues
Author-email: Coldbricks <coldbricks@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: rate-limit,threshold,throttle,token-bucket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# edging

Rate limiting that approaches but never exceeds a threshold. Implements a
classic token-bucket limiter with an optional ``hold_at_threshold()`` mode
for steady approach without burst overshoot.

## Install

```bash
pip install edging
```

## Usage

```python
from edging import TokenBucket, RateLimitExceeded

bucket = TokenBucket(rate=5.0, capacity=5.0).hold_at_threshold(True)
assert bucket.acquire(1.0) is True
assert bucket.tokens() < 5.0

try:
    # exhaust then fail closed without blocking
    for _ in range(10):
        bucket.acquire(1.0, blocking=False)
except RateLimitExceeded as e:
    assert e.retry_after > 0
```

## Roadmap

This is an early **0.1.0** release with active development planned:

- Async acquire APIs
- Shared / distributed backends
- Adaptive threshold policies

## Author

Coldbricks — coldbricks@gmail.com
