# 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
python -m twine upload dist/*
```
Remember to bump the version in `pyproject.toml` and `token_limit_guard/__init__.py`
before publishing.
Raw data
{
"_id": null,
"home_page": null,
"name": "token-limit-guard",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "tokens, rate-limiting, lru, throttling",
"author": null,
"author_email": "Imranur Rahman <ir.shimul@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/78/f9/a985a9f75d747115cfd85200c066502d54d0a139bc273059a3432f8ba5d7/token_limit_guard-0.1.0.tar.gz",
"platform": null,
"description": "# token-limit-guard\n\nLeast recently used token allocator with per-token rate limiting and optional\nblocking behavior. Perfect for juggling API keys or access tokens that must\nrespect individual quotas.\n\n## Features\n\n- Accept tokens from a file or in-memory iterable\n- Configure rate limiting per token with a rolling time window\n- Blocking and non-blocking retrieval modes\n- Simple LRU selection to balance token usage\n- Thread-safe implementation with helpful logging for debugging\n\n## Installation\n\nThe package is published on PyPI:\n\n```bash\npip install token-limit-guard\n```\n\n## Quickstart\n\n```python\nfrom token_limit_guard import TokenLimitGuard\n\ntoken_guard = TokenLimitGuard([\"tokenA\", \"tokenB\", \"tokenC\"])\ntoken_guard.set_limiting_factors(max_allowed_count=2, time_window_in_sec=60)\n\n# Blocking call \u2013 waits for the next available token if all are exhausted\ntoken = token_guard.get_a_token()\n\n# Non-blocking call \u2013 returns None immediately when no token is available\nmaybe_token = token_guard.get_a_token(block=False)\n\n# Convenience alias for non-blocking access\nmaybe_token = token_guard.try_get_a_token()\n\nprint(token)\n```\n\n## Development\n\nInstall dev dependencies and run the tests with `pytest`:\n\n```bash\npython -m venv .token-venv\nsource .token-venv/bin/activate # or .venv\\\\Scripts\\\\activate on Windows\npip install -e .[dev] # pip install -e '.[dev]'\npytest\n```\n\n## Publishing to PyPI\n\n```bash\npip install --upgrade build\npython -m build\npython -m twine upload dist/*\n```\n\nRemember to bump the version in `pyproject.toml` and `token_limit_guard/__init__.py`\nbefore publishing.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Least recently used token allocator with per-token rate limiting",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/imranur-rahman/token-limit-guard",
"Issues": "https://github.com/imranur-rahman/token-limit-guard/issues",
"Repository": "https://github.com/imranur-rahman/token-limit-guard"
},
"split_keywords": [
"tokens",
" rate-limiting",
" lru",
" throttling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5572de65697a3e834428a5c0a6f4f24a535e4714d9f5cd94a6851a5d4f68307f",
"md5": "12b54994a8682057ff76976fc90865e3",
"sha256": "5580cf3a1f822f135050d547ba43a6945ed65b6aa263d560b8e0373423cc0403"
},
"downloads": -1,
"filename": "token_limit_guard-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12b54994a8682057ff76976fc90865e3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 5811,
"upload_time": "2025-10-08T22:52:35",
"upload_time_iso_8601": "2025-10-08T22:52:35.668875Z",
"url": "https://files.pythonhosted.org/packages/55/72/de65697a3e834428a5c0a6f4f24a535e4714d9f5cd94a6851a5d4f68307f/token_limit_guard-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "78f9a985a9f75d747115cfd85200c066502d54d0a139bc273059a3432f8ba5d7",
"md5": "7224212024128b62c1309141520f9966",
"sha256": "8b4137fddc52d7f5ef438925dea7752abc93a638ae2039ce7566d4e5e8c25cfd"
},
"downloads": -1,
"filename": "token_limit_guard-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7224212024128b62c1309141520f9966",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6190,
"upload_time": "2025-10-08T22:52:37",
"upload_time_iso_8601": "2025-10-08T22:52:37.099527Z",
"url": "https://files.pythonhosted.org/packages/78/f9/a985a9f75d747115cfd85200c066502d54d0a139bc273059a3432f8ba5d7/token_limit_guard-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 22:52:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "imranur-rahman",
"github_project": "token-limit-guard",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "token-limit-guard"
}
JSON
