Metadata-Version: 2.4
Name: rate-limit-safe-token-allocator
Version: 0.1.1
Summary: Rate limit safe token allocator with least recently used (LRU) strategy if multiple tokens are available and will avoid rate limit errors.
Author-email: Imranur Rahman <ir.shimul@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/imranur-rahman/token-limit-guard
Project-URL: Repository, https://github.com/imranur-rahman/token-limit-guard
Project-URL: Issues, https://github.com/imranur-rahman/token-limit-guard/issues
Keywords: tokens,rate-limiting,lru,throttling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# token-limit-guard

Least recently used token allocator with per-token rate limiting and optional
blocking behavior. Perfect for juggling API keys or access tokens that must
respect individual quotas.

## Features

- Accept tokens from a file or in-memory iterable
- Configure rate limiting per token with a rolling time window
- Blocking and non-blocking retrieval modes
- Simple LRU selection to balance token usage
- Thread-safe implementation with helpful logging for debugging

## Installation

The package is published on PyPI:

```bash
pip install token-limit-guard
```

## Quickstart

```python
from token_limit_guard import TokenLimitGuard

token_guard = TokenLimitGuard(["tokenA", "tokenB", "tokenC"])
token_guard.set_limiting_factors(max_allowed_count=2, time_window_in_sec=60)

# Blocking call – waits for the next available token if all are exhausted
token = token_guard.get_a_token()

# Non-blocking call – returns None immediately when no token is available
maybe_token = token_guard.get_a_token(block=False)

# Convenience alias for non-blocking access
maybe_token = token_guard.try_get_a_token()

print(token)
```

## Development

Install dev dependencies and run the tests with `pytest`:

```bash
python -m venv .token-venv
source .token-venv/bin/activate  # or .venv\\Scripts\\activate on Windows
pip install -e .[dev] # pip install -e '.[dev]'
pytest
```

## Publishing to PyPI

```bash
pip install --upgrade build
python -m build
pip install --upgrade twine
python -m twine upload dist/*
```

Remember to bump the version in `pyproject.toml` and `token_limit_guard/__init__.py`
before publishing.
