open-keypool 0.2.1__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: Bug report
3
+ about: Report a reproducible problem
4
+ title: "[Bug] "
5
+ labels: bug
6
+ ---
7
+
8
+ ## Description
9
+
10
+ ## Reproduction
11
+
12
+ ```python
13
+ # Minimal example
14
+ ```
15
+
16
+ ## Expected behavior
17
+
18
+ ## Environment
19
+
20
+ - open-keypool version:
21
+ - Python version:
22
+ - Operating system:
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: Feature request
3
+ about: Suggest a small, useful improvement
4
+ title: "[Feature] "
5
+ labels: enhancement
6
+ ---
7
+
8
+ ## Problem
9
+
10
+ ## Proposed solution
11
+
12
+ ## Alternatives considered
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: pip
4
+ directory: "/"
5
+ schedule:
6
+ interval: weekly
7
+ - package-ecosystem: github-actions
8
+ directory: "/"
9
+ schedule:
10
+ interval: weekly
@@ -0,0 +1,11 @@
1
+ ## Summary
2
+
3
+ ## Tests
4
+
5
+ - [ ] `pytest`
6
+ - [ ] Documentation updated if needed
7
+
8
+ ## Checklist
9
+
10
+ - [ ] No raw API keys or credentials are included
11
+ - [ ] Python 3.9 compatibility is preserved
@@ -0,0 +1,27 @@
1
+ name: Publish
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ publish:
13
+ runs-on: ubuntu-latest
14
+ environment: pypi
15
+ permissions:
16
+ id-token: write
17
+ steps:
18
+ - uses: actions/checkout@v4.2.2
19
+ - uses: actions/setup-python@v5.6.0
20
+ with:
21
+ python-version: "3.12"
22
+ - name: Build
23
+ run: |
24
+ python -m pip install --upgrade build
25
+ python -m build
26
+ - name: Publish to PyPI
27
+ uses: pypa/gh-action-pypi-publish@v1.14.3
@@ -0,0 +1,31 @@
1
+ name: Test Suite
2
+
3
+ on:
4
+ push:
5
+ branches: [ main ]
6
+ pull_request:
7
+ branches: [ main ]
8
+
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-24.04
12
+ strategy:
13
+ matrix:
14
+ python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
15
+
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - name: Set up Python ${{ matrix.python-version }}
20
+ uses: actions/setup-python@v5
21
+ with:
22
+ python-version: ${{ matrix.python-version }}
23
+
24
+ - name: Install dependencies
25
+ run: |
26
+ python -m pip install --upgrade pip
27
+ pip install -e ".[dev,env]"
28
+
29
+ - name: Run Pytest
30
+ run: |
31
+ pytest
File without changes
@@ -0,0 +1,54 @@
1
+ # Changelog
2
+
3
+ All notable changes to `open-keypool` will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.4.0] - 2026-11-20
9
+
10
+ ### Added
11
+ - Added transient 408/5xx cooldowns, optional recovery waiting, safe callbacks, and masked logging.
12
+ - Added `KeyPoolAuth` for sync and async `httpx` clients.
13
+ - Added OpenRouter, Cerebras, Mistral, and Anthropic provider presets.
14
+ - Added release, contribution, issue-template, and Dependabot configuration.
15
+
16
+ ### Changed (behavior)
17
+ - Client errors other than documented authentication and rate-limit signals now stay ACTIVE, do not increment `failure_count`, and are returned immediately by `call()`.
18
+ - 408 and 5xx responses use the new five-second transient cooldown by default; `Retry-After` still wins.
19
+ - Added a `Typing :: Typed` package marker and bumped the package version to 0.4.0.
20
+
21
+ ### Fixed
22
+ - Prevented raw API keys from appearing in record representations, status snapshots, exceptions, callbacks, and logs.
23
+ - Kept constructor options consistent across all sync and async secret loaders.
24
+
25
+ ## [0.3.0] - 2026-09-25
26
+
27
+ ### Added
28
+ - **Async Support**: Added `AsyncKeyPool` class supporting `async get_key()`, `async_get_key()`, `async handle_response()`, `async call()`, and async Doppler loading via `httpx.AsyncClient`.
29
+ - **High-level `pool.call()`**: Added `pool.call(fn, *args, **kwargs)` (sync & async) to execute request callables with automatic key selection, response handling, and retries.
30
+ - **Provider Presets**: Added `provider` parameter (`"groq"`, `"openai"`, `"gemini"`, `"together"`) to pre-configure rate-limit headers (e.g., `x-ratelimit-reset-*`, `retry-after-ms`) and provider-specific error body structures.
31
+ - **Cloud Secrets Loaders**: Added `KeyPool.from_aws_secrets()` (boto3) and `KeyPool.from_gcp_secrets()` (google-cloud-secret-manager) classmethods.
32
+ - **FastAPI Middleware Example**: Added `examples/fastapi_middleware.py`.
33
+ - **CI Workflow**: Added GitHub Actions workflow `.github/workflows/test.yml` running pytest across Python 3.9–3.13.
34
+
35
+ ### Fixed
36
+ - **Doppler Cache Key**: Included `token` in `from_doppler()`'s in-memory cache key to prevent stale cache hits upon token rotation.
37
+ - **Status Key Collisions**: Fixed `status()` key collisions by appending disambiguating suffixes (e.g. `sk-abc...1234#2`) when multiple keys mask to the same representation.
38
+ - **Optional `python-dotenv`**: Moved `python-dotenv` from core dependencies into an `env` optional extra (`pip install open-keypool[env]`) with lazy import error messaging inside `from_env()`.
39
+ - **Documentation Link**: Updated documentation URL to `https://tusharneje.in/projects/open-keypool/`.
40
+
41
+ ---
42
+
43
+ ## [0.2.1] - 2026-08-25
44
+
45
+ ### Fixed
46
+ - Updated PyPI package metadata and README documentation links for canonical PyPI and GitHub usage.
47
+
48
+ ---
49
+
50
+ ## [0.2.0] - 2026-08-25
51
+
52
+ ### Added
53
+ - Classmethods `KeyPool.from_env(suffix, env_file=None)` and `KeyPool.from_json(path, suffix=None)` for loading API keys with suffix filtering.
54
+ - Thread-safe key additions and removals dynamically at runtime.
@@ -0,0 +1,20 @@
1
+ # Contributing
2
+
3
+ ## Setup
4
+
5
+ ```bash
6
+ python -m venv .venv
7
+ . .venv/bin/activate
8
+ pip install -e ".[dev,env]"
9
+ ```
10
+
11
+ ## Tests
12
+
13
+ Run `pytest`. The CI matrix tests Python 3.9 through 3.13.
14
+
15
+ ## Adding a provider preset
16
+
17
+ Verify the provider's official status codes, error body fields, and retry
18
+ headers first. Add only documented signals to the data-driven rules in
19
+ `src/open_keypool/core.py`, then add sync and async tests. Unknown provider
20
+ names must continue to use the generic rules.
File without changes
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: open-keypool
3
- Version: 0.2.1
3
+ Version: 0.4.0
4
4
  Summary: Minimal Python library for pooling and rotating API keys to avoid HTTP 429 rate-limit errors.
5
5
  Project-URL: Homepage, https://github.com/tusharneje-07/open-keypool
6
6
  Project-URL: Repository, https://github.com/tusharneje-07/open-keypool
7
- Project-URL: Documentation, https://github.com/tusharneje-07/open-keypool/blob/main/docs/index.html
7
+ Project-URL: Documentation, https://tusharneje.in/projects/open-keypool/
8
8
  Project-URL: Bug Tracker, https://github.com/tusharneje-07/open-keypool/issues
9
- Author: Open KeyPool Contributors
9
+ Author: Tushar Neje
10
10
  License: MIT License
11
11
 
12
12
  Copyright (c) 2026 Open KeyPool Contributors
@@ -29,7 +29,7 @@ License: MIT License
29
29
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
30
  SOFTWARE.
31
31
  License-File: LICENSE
32
- Keywords: api-keys,key-pool,key-rotation,rate-limiting
32
+ Keywords: groq,hackathon,llm,openai,rate-limit
33
33
  Classifier: Development Status :: 4 - Beta
34
34
  Classifier: Intended Audience :: Developers
35
35
  Classifier: License :: OSI Approved :: MIT License
@@ -39,18 +39,34 @@ Classifier: Programming Language :: Python :: 3.10
39
39
  Classifier: Programming Language :: Python :: 3.11
40
40
  Classifier: Programming Language :: Python :: 3.12
41
41
  Classifier: Programming Language :: Python :: 3.13
42
+ Classifier: Typing :: Typed
42
43
  Requires-Python: >=3.9
43
44
  Requires-Dist: cachetools>=5.3.0
44
45
  Requires-Dist: httpx>=0.27.0
45
- Requires-Dist: python-dotenv>=1.0.0
46
+ Provides-Extra: all
47
+ Requires-Dist: boto3>=1.26.0; extra == 'all'
48
+ Requires-Dist: google-cloud-secret-manager>=2.16.0; extra == 'all'
49
+ Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
50
+ Provides-Extra: aws
51
+ Requires-Dist: boto3>=1.26.0; extra == 'aws'
46
52
  Provides-Extra: dev
47
53
  Requires-Dist: pdoc>=15.0.0; extra == 'dev'
48
54
  Requires-Dist: pytest>=8.0.0; extra == 'dev'
49
55
  Requires-Dist: respx>=0.22.0; extra == 'dev'
56
+ Provides-Extra: env
57
+ Requires-Dist: python-dotenv>=1.0.0; extra == 'env'
58
+ Provides-Extra: gcp
59
+ Requires-Dist: google-cloud-secret-manager>=2.16.0; extra == 'gcp'
50
60
  Description-Content-Type: text/markdown
51
61
 
52
62
  # open-keypool
53
63
 
64
+ [![PyPI](https://img.shields.io/pypi/v/open-keypool)](https://pypi.org/project/open-keypool/)
65
+ [![Python](https://img.shields.io/pypi/pyversions/open-keypool)](https://pypi.org/project/open-keypool/)
66
+ [![License](https://img.shields.io/pypi/l/open-keypool)](LICENSE)
67
+ [![CI](https://github.com/tusharneje-07/open-keypool/actions/workflows/test.yml/badge.svg)](https://github.com/tusharneje-07/open-keypool/actions/workflows/test.yml)
68
+ [![Downloads](https://static.pepy.tech/badge/open-keypool)](https://pepy.tech/project/open-keypool)
69
+
54
70
  Minimal Python library for pooling and rotating API keys to avoid HTTP 429 rate-limit errors. Provide a list of keys (or pull them from Doppler, `.env`, or JSON), choose a rotation strategy (round-robin or least-recently-used), and the pool handles cooldown on rate-limit responses and permanent disablement on invalid keys — all thread-safe.
55
71
 
56
72
  ## Install
@@ -61,7 +77,52 @@ pip install open-keypool
61
77
 
62
78
  ## Quickstart
63
79
 
64
- ### Local keys array
80
+ ### High-level pool.call() (Recommended)
81
+
82
+ `pool.call(fn, *args, **kwargs)` runs the `get_key → fn → handle_response` loop automatically:
83
+
84
+ ```python
85
+ import httpx
86
+ from open_keypool import KeyPool
87
+
88
+ pool = KeyPool(keys=["sk-key1", "sk-key2", "sk-key3"], provider="groq")
89
+
90
+ # Collapses execution down to 3 lines with automatic key rotation and retries:
91
+ def fetch_chat(key):
92
+ return httpx.get("https://api.groq.com/v1/models", headers={"Authorization": f"Bearer {key}"})
93
+
94
+ response = pool.call(fetch_chat)
95
+ ```
96
+
97
+ ### Async Usage (`AsyncKeyPool`)
98
+
99
+ ```python
100
+ import httpx
101
+ import asyncio
102
+ from open_keypool import AsyncKeyPool
103
+
104
+ async def main():
105
+ pool = AsyncKeyPool(keys=["sk-key1", "sk-key2"], provider="openai")
106
+
107
+ async def fetch_models(key):
108
+ async with httpx.AsyncClient() as client:
109
+ return await client.get("https://api.openai.com/v1/models", headers={"Authorization": f"Bearer {key}"})
110
+
111
+ response = await pool.call(fetch_models)
112
+
113
+ asyncio.run(main())
114
+ ```
115
+
116
+ ### Provider Presets
117
+
118
+ Pre-configure how response rate-limit headers and error structures are handled (`"groq"`, `"openai"`, `"gemini"`, `"together"`, `"openrouter"`, `"cerebras"`, `"mistral"`, `"anthropic"`):
119
+
120
+ ```python
121
+ pool = KeyPool(keys=["sk-groq-1", "sk-groq-2"], provider="groq")
122
+ # Automatically handles Groq rate limit headers (x-ratelimit-reset-requests, etc.)
123
+ ```
124
+
125
+ ### Manual rotation loop
65
126
 
66
127
  ```python
67
128
  from open_keypool import KeyPool, AllKeysExhaustedError, KeyState
@@ -96,7 +157,8 @@ for attempt in range(pool.max_retries):
96
157
  | **2xx** | Marks success — clears errors, resets failure count |
97
158
  | **429**, **413**, or `"rate_limit_exceeded"` in body | Marks cooldown, reads `Retry-After` header |
98
159
  | **401**, **403** | Permanently disables the key |
99
- | **5xx** | Places on cooldown (transient) |
160
+ | **408**, **5xx** | Places on a short transient cooldown |
161
+ | Other **4xx** | Stays active and is returned to the caller |
100
162
 
101
163
  Returns `KeyState` so you can branch on the result.
102
164
 
@@ -129,30 +191,27 @@ for masked_key, info in pool.status().items():
129
191
  ```python
130
192
  from open_keypool import KeyPool
131
193
 
132
- # .env contains:
133
- # TSN_GROQ_KEY=sk-aaa
134
- # BACKUP_GROQ_KEY=sk-bbb
135
- # OTHER_SECRET=sk-ccc
136
-
137
194
  pool = KeyPool.from_env(suffix="GROQ_KEY")
138
- # Picks TSN_GROQ_KEY and BACKUP_GROQ_KEY (ends with "GROQ_KEY")
139
195
  ```
140
196
 
141
197
  ### Load keys from JSON file
142
198
 
143
- ```json
144
- {
145
- "TSN_GROQ_KEY": "sk-aaa",
146
- "BACKUP_GROQ_KEY": "sk-bbb",
147
- "OTHER_SECRET": "sk-ccc"
148
- }
199
+ ```python
200
+ from open_keypool import KeyPool
201
+
202
+ pool = KeyPool.from_json("keys.json", suffix="GROQ_KEY")
149
203
  ```
150
204
 
205
+ ### Load keys from AWS Secrets Manager or GCP Secret Manager
206
+
151
207
  ```python
152
208
  from open_keypool import KeyPool
153
209
 
154
- pool = KeyPool.from_json("keys.json", suffix="GROQ_KEY")
155
- # Picks TSN_GROQ_KEY and BACKUP_GROQ_KEY (ends with "GROQ_KEY")
210
+ # AWS Secrets Manager (requires open-keypool[aws] or boto3)
211
+ aws_pool = KeyPool.from_aws_secrets("my-app-secrets", key_prefix="GROQ_")
212
+
213
+ # GCP Secret Manager (requires open-keypool[gcp] or google-cloud-secret-manager)
214
+ gcp_pool = KeyPool.from_gcp_secrets("my-app-secrets", project_id="my-project", key_prefix="GROQ_")
156
215
  ```
157
216
 
158
217
  ## Constructor parameters
@@ -163,6 +222,63 @@ pool = KeyPool.from_json("keys.json", suffix="GROQ_KEY")
163
222
  | `max_retries` | `int` | `3` | Max retry count reference for the caller's loop. |
164
223
  | `cooldown_seconds` | `int` | `60` | How long a rate-limited key stays in cooldown. |
165
224
  | `strategy` | `str` | `"round_robin"` | Rotation strategy: `"round_robin"` or `"lru"`. |
225
+ | `provider` | `str` | `None` | Provider preset: `"groq"`, `"openai"`, `"gemini"`, `"together"`, `"openrouter"`, `"cerebras"`, `"mistral"`, or `"anthropic"`. |
226
+ | `transient_cooldown_seconds` | `float` | `5` | Cooldown for 408 and 5xx responses. |
227
+ | `wait_for_recovery` | `bool` | `False` | Let `call()` wait for a cooling-down key. |
228
+ | `max_wait_seconds` | `float` | `30.0` | Maximum wait budget for one call. |
229
+ | `on_cooldown`, `on_disabled`, `on_exhausted` | callback | `None` | Optional lifecycle callbacks; keys are masked. |
230
+
231
+ ### `httpx` authentication
232
+
233
+ Use `KeyPoolAuth` with any client that accepts a custom `httpx` client:
234
+
235
+ ```python
236
+ import httpx
237
+ from open_keypool import KeyPool, KeyPoolAuth
238
+
239
+ pool = KeyPool(["key-one", "key-two"], provider="openai")
240
+ with httpx.Client(auth=KeyPoolAuth(pool)) as client:
241
+ response = client.get("https://api.openai.com/v1/models")
242
+ ```
243
+
244
+ Set `scheme=None` for raw-key headers such as `x-goog-api-key`. Use
245
+ `AsyncKeyPool` with `httpx.AsyncClient`; async callbacks are supported.
246
+
247
+ ### Logging
248
+
249
+ The library uses the `open_keypool` logger. It installs a `NullHandler` by
250
+ default; applications can opt in to INFO/WARNING lifecycle messages or DEBUG
251
+ rotation messages with normal Python logging configuration. Keys are always
252
+ masked.
253
+
254
+ ### 5-minute hackathon setup
255
+
256
+ ```bash
257
+ python -m venv .venv && . .venv/bin/activate
258
+ pip install open-keypool
259
+ ```
260
+
261
+ Put `KEY_1` and `KEY_2` in your environment, then:
262
+
263
+ ```python
264
+ import os
265
+ import httpx
266
+ from open_keypool import KeyPool
267
+
268
+ pool = KeyPool([os.environ["KEY_1"], os.environ["KEY_2"]], provider="groq")
269
+ response = pool.call(
270
+ lambda key: httpx.get(
271
+ "https://api.groq.com/openai/v1/models",
272
+ headers={"Authorization": f"Bearer {key}"},
273
+ )
274
+ )
275
+ print(response.status_code)
276
+ ```
277
+
278
+ ### Limitations
279
+
280
+ State is per-process. Each gunicorn/uvicorn worker has its own view of the
281
+ keys, and this package is not a distributed rate limiter.
166
282
 
167
283
  ## Doppler caching
168
284
 
@@ -172,4 +288,27 @@ Pass `force_refresh=True` to bypass the cache and re-fetch immediately (useful a
172
288
 
173
289
  ## Full API reference
174
290
 
175
- [docs/index.html](https://github.com/tusharneje-07/open-keypool/blob/main/docs/index.html) — self-contained HTML page with quickstart + class/method documentation generated from docstrings.
291
+ Read [Docs](https://tusharneje.in/projects/open-keypool/).
292
+
293
+ ## Contributing
294
+
295
+ Contributions are welcome. If you have an idea, find a bug, or want to improve `open-keypool`, feel free to contribute.
296
+
297
+ ### How to Contribute
298
+
299
+ 1. Fork the repository.
300
+ 2. Create a new branch for your changes.
301
+ 3. Make your changes and add appropriate tests.
302
+ 4. Run the test suite and make sure all tests pass.
303
+ 5. Commit your changes with a clear message.
304
+ 6. Open a Pull Request describing what you changed and why.
305
+
306
+ Please keep contributions focused on the core goal of `open-keypool`: **simple and reliable API key pooling and rotation**.
307
+
308
+ For larger changes or new features, open an issue first so the approach can be discussed before implementation.
309
+
310
+ ## License
311
+
312
+ `open-keypool` is released under the [MIT License](LICENSE).
313
+
314
+ See the `LICENSE` file for the full license text.