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.
@@ -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
@@ -8,7 +8,7 @@ on:
8
8
 
9
9
  jobs:
10
10
  test:
11
- runs-on: ubuntu-latest
11
+ runs-on: ubuntu-24.04
12
12
  strategy:
13
13
  matrix:
14
14
  python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
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.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: 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,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
+ [![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
+
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 cooldown (transient) |
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
+ [![PyPI](https://img.shields.io/pypi/v/open-keypool)](https://pypi.org/project/open-keypool/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/open-keypool)](https://pypi.org/project/open-keypool/)
5
+ [![License](https://img.shields.io/pypi/l/open-keypool)](LICENSE)
6
+ [![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)
7
+ [![Downloads](https://static.pepy.tech/badge/open-keypool)](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 cooldown (transient) |
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.