open-keypool 0.3.0__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.
- open_keypool-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md +22 -0
- open_keypool-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md +12 -0
- open_keypool-0.4.0/.github/dependabot.yml +10 -0
- open_keypool-0.4.0/.github/pull_request_template.md +11 -0
- open_keypool-0.4.0/.github/workflows/publish.yml +27 -0
- {open_keypool-0.3.0 → open_keypool-0.4.0}/.github/workflows/test.yml +1 -1
- {open_keypool-0.3.0 → open_keypool-0.4.0}/.gitignore +0 -0
- {open_keypool-0.3.0 → open_keypool-0.4.0}/CHANGELOG.md +17 -0
- open_keypool-0.4.0/CONTRIBUTING.md +20 -0
- {open_keypool-0.3.0 → open_keypool-0.4.0}/LICENSE +0 -0
- {open_keypool-0.3.0 → open_keypool-0.4.0}/PKG-INFO +71 -7
- {open_keypool-0.3.0 → open_keypool-0.4.0}/README.md +67 -4
- open_keypool-0.4.0/docs/index.html +4271 -0
- {open_keypool-0.3.0 → open_keypool-0.4.0}/examples/fastapi_middleware.py +0 -0
- open_keypool-0.4.0/examples/httpx_auth.py +18 -0
- {open_keypool-0.3.0 → open_keypool-0.4.0}/pyproject.toml +4 -3
- {open_keypool-0.3.0 → open_keypool-0.4.0}/src/open_keypool/__init__.py +8 -1
- {open_keypool-0.3.0 → open_keypool-0.4.0}/src/open_keypool/core.py +274 -106
- open_keypool-0.4.0/src/open_keypool/httpx_auth.py +65 -0
- {open_keypool-0.3.0 → open_keypool-0.4.0}/src/open_keypool/py.typed +0 -0
- {open_keypool-0.3.0 → open_keypool-0.4.0}/tests/test_core.py +0 -0
- open_keypool-0.4.0/tests/test_v040_regressions.py +147 -0
- open_keypool-0.3.0/docs/index.html +0 -2433
|
@@ -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,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
|
|
File without changes
|
|
@@ -5,6 +5,23 @@ All notable changes to `open-keypool` will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
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
|
+
|
|
8
25
|
## [0.3.0] - 2026-09-25
|
|
9
26
|
|
|
10
27
|
### Added
|
|
@@ -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.
|
|
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
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:
|
|
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:
|
|
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,6 +39,7 @@ 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
|
|
@@ -60,6 +61,12 @@ Description-Content-Type: text/markdown
|
|
|
60
61
|
|
|
61
62
|
# open-keypool
|
|
62
63
|
|
|
64
|
+
[](https://pypi.org/project/open-keypool/)
|
|
65
|
+
[](https://pypi.org/project/open-keypool/)
|
|
66
|
+
[](LICENSE)
|
|
67
|
+
[](https://github.com/tusharneje-07/open-keypool/actions/workflows/test.yml)
|
|
68
|
+
[](https://pepy.tech/project/open-keypool)
|
|
69
|
+
|
|
63
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.
|
|
64
71
|
|
|
65
72
|
## Install
|
|
@@ -108,7 +115,7 @@ asyncio.run(main())
|
|
|
108
115
|
|
|
109
116
|
### Provider Presets
|
|
110
117
|
|
|
111
|
-
Pre-configure how response rate-limit headers and error structures are handled (`"groq"`, `"openai"`, `"gemini"`, `"together"`):
|
|
118
|
+
Pre-configure how response rate-limit headers and error structures are handled (`"groq"`, `"openai"`, `"gemini"`, `"together"`, `"openrouter"`, `"cerebras"`, `"mistral"`, `"anthropic"`):
|
|
112
119
|
|
|
113
120
|
```python
|
|
114
121
|
pool = KeyPool(keys=["sk-groq-1", "sk-groq-2"], provider="groq")
|
|
@@ -150,7 +157,8 @@ for attempt in range(pool.max_retries):
|
|
|
150
157
|
| **2xx** | Marks success — clears errors, resets failure count |
|
|
151
158
|
| **429**, **413**, or `"rate_limit_exceeded"` in body | Marks cooldown, reads `Retry-After` header |
|
|
152
159
|
| **401**, **403** | Permanently disables the key |
|
|
153
|
-
| **5xx** | Places on
|
|
160
|
+
| **408**, **5xx** | Places on a short transient cooldown |
|
|
161
|
+
| Other **4xx** | Stays active and is returned to the caller |
|
|
154
162
|
|
|
155
163
|
Returns `KeyState` so you can branch on the result.
|
|
156
164
|
|
|
@@ -214,7 +222,63 @@ gcp_pool = KeyPool.from_gcp_secrets("my-app-secrets", project_id="my-project", k
|
|
|
214
222
|
| `max_retries` | `int` | `3` | Max retry count reference for the caller's loop. |
|
|
215
223
|
| `cooldown_seconds` | `int` | `60` | How long a rate-limited key stays in cooldown. |
|
|
216
224
|
| `strategy` | `str` | `"round_robin"` | Rotation strategy: `"round_robin"` or `"lru"`. |
|
|
217
|
-
| `provider` | `str` | `None` | Provider preset: `"groq"`, `"openai"`, `"gemini"`, `"together"`. |
|
|
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.
|
|
218
282
|
|
|
219
283
|
## Doppler caching
|
|
220
284
|
|
|
@@ -247,4 +311,4 @@ For larger changes or new features, open an issue first so the approach can be d
|
|
|
247
311
|
|
|
248
312
|
`open-keypool` is released under the [MIT License](LICENSE).
|
|
249
313
|
|
|
250
|
-
See the `LICENSE` file for the full license text.
|
|
314
|
+
See the `LICENSE` file for the full license text.
|
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# open-keypool
|
|
2
2
|
|
|
3
|
+
[](https://pypi.org/project/open-keypool/)
|
|
4
|
+
[](https://pypi.org/project/open-keypool/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://github.com/tusharneje-07/open-keypool/actions/workflows/test.yml)
|
|
7
|
+
[](https://pepy.tech/project/open-keypool)
|
|
8
|
+
|
|
3
9
|
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.
|
|
4
10
|
|
|
5
11
|
## Install
|
|
@@ -48,7 +54,7 @@ asyncio.run(main())
|
|
|
48
54
|
|
|
49
55
|
### Provider Presets
|
|
50
56
|
|
|
51
|
-
Pre-configure how response rate-limit headers and error structures are handled (`"groq"`, `"openai"`, `"gemini"`, `"together"`):
|
|
57
|
+
Pre-configure how response rate-limit headers and error structures are handled (`"groq"`, `"openai"`, `"gemini"`, `"together"`, `"openrouter"`, `"cerebras"`, `"mistral"`, `"anthropic"`):
|
|
52
58
|
|
|
53
59
|
```python
|
|
54
60
|
pool = KeyPool(keys=["sk-groq-1", "sk-groq-2"], provider="groq")
|
|
@@ -90,7 +96,8 @@ for attempt in range(pool.max_retries):
|
|
|
90
96
|
| **2xx** | Marks success — clears errors, resets failure count |
|
|
91
97
|
| **429**, **413**, or `"rate_limit_exceeded"` in body | Marks cooldown, reads `Retry-After` header |
|
|
92
98
|
| **401**, **403** | Permanently disables the key |
|
|
93
|
-
| **5xx** | Places on
|
|
99
|
+
| **408**, **5xx** | Places on a short transient cooldown |
|
|
100
|
+
| Other **4xx** | Stays active and is returned to the caller |
|
|
94
101
|
|
|
95
102
|
Returns `KeyState` so you can branch on the result.
|
|
96
103
|
|
|
@@ -154,7 +161,63 @@ gcp_pool = KeyPool.from_gcp_secrets("my-app-secrets", project_id="my-project", k
|
|
|
154
161
|
| `max_retries` | `int` | `3` | Max retry count reference for the caller's loop. |
|
|
155
162
|
| `cooldown_seconds` | `int` | `60` | How long a rate-limited key stays in cooldown. |
|
|
156
163
|
| `strategy` | `str` | `"round_robin"` | Rotation strategy: `"round_robin"` or `"lru"`. |
|
|
157
|
-
| `provider` | `str` | `None` | Provider preset: `"groq"`, `"openai"`, `"gemini"`, `"together"`. |
|
|
164
|
+
| `provider` | `str` | `None` | Provider preset: `"groq"`, `"openai"`, `"gemini"`, `"together"`, `"openrouter"`, `"cerebras"`, `"mistral"`, or `"anthropic"`. |
|
|
165
|
+
| `transient_cooldown_seconds` | `float` | `5` | Cooldown for 408 and 5xx responses. |
|
|
166
|
+
| `wait_for_recovery` | `bool` | `False` | Let `call()` wait for a cooling-down key. |
|
|
167
|
+
| `max_wait_seconds` | `float` | `30.0` | Maximum wait budget for one call. |
|
|
168
|
+
| `on_cooldown`, `on_disabled`, `on_exhausted` | callback | `None` | Optional lifecycle callbacks; keys are masked. |
|
|
169
|
+
|
|
170
|
+
### `httpx` authentication
|
|
171
|
+
|
|
172
|
+
Use `KeyPoolAuth` with any client that accepts a custom `httpx` client:
|
|
173
|
+
|
|
174
|
+
```python
|
|
175
|
+
import httpx
|
|
176
|
+
from open_keypool import KeyPool, KeyPoolAuth
|
|
177
|
+
|
|
178
|
+
pool = KeyPool(["key-one", "key-two"], provider="openai")
|
|
179
|
+
with httpx.Client(auth=KeyPoolAuth(pool)) as client:
|
|
180
|
+
response = client.get("https://api.openai.com/v1/models")
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Set `scheme=None` for raw-key headers such as `x-goog-api-key`. Use
|
|
184
|
+
`AsyncKeyPool` with `httpx.AsyncClient`; async callbacks are supported.
|
|
185
|
+
|
|
186
|
+
### Logging
|
|
187
|
+
|
|
188
|
+
The library uses the `open_keypool` logger. It installs a `NullHandler` by
|
|
189
|
+
default; applications can opt in to INFO/WARNING lifecycle messages or DEBUG
|
|
190
|
+
rotation messages with normal Python logging configuration. Keys are always
|
|
191
|
+
masked.
|
|
192
|
+
|
|
193
|
+
### 5-minute hackathon setup
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
python -m venv .venv && . .venv/bin/activate
|
|
197
|
+
pip install open-keypool
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Put `KEY_1` and `KEY_2` in your environment, then:
|
|
201
|
+
|
|
202
|
+
```python
|
|
203
|
+
import os
|
|
204
|
+
import httpx
|
|
205
|
+
from open_keypool import KeyPool
|
|
206
|
+
|
|
207
|
+
pool = KeyPool([os.environ["KEY_1"], os.environ["KEY_2"]], provider="groq")
|
|
208
|
+
response = pool.call(
|
|
209
|
+
lambda key: httpx.get(
|
|
210
|
+
"https://api.groq.com/openai/v1/models",
|
|
211
|
+
headers={"Authorization": f"Bearer {key}"},
|
|
212
|
+
)
|
|
213
|
+
)
|
|
214
|
+
print(response.status_code)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Limitations
|
|
218
|
+
|
|
219
|
+
State is per-process. Each gunicorn/uvicorn worker has its own view of the
|
|
220
|
+
keys, and this package is not a distributed rate limiter.
|
|
158
221
|
|
|
159
222
|
## Doppler caching
|
|
160
223
|
|
|
@@ -187,4 +250,4 @@ For larger changes or new features, open an issue first so the approach can be d
|
|
|
187
250
|
|
|
188
251
|
`open-keypool` is released under the [MIT License](LICENSE).
|
|
189
252
|
|
|
190
|
-
See the `LICENSE` file for the full license text.
|
|
253
|
+
See the `LICENSE` file for the full license text.
|