keycycle 0.3.1__tar.gz → 0.3.2__tar.gz

{keycycle-0.3.1 → keycycle-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keycycle
-Version: 0.3.1
+Version: 0.3.2
 Summary: A thread-safe key rotation and rate limiting manager for API keys.
 Author-email: William Jin <jinwilliam.jin@gmail.com>
 Classifier: Programming Language :: Python :: 3

{keycycle-0.3.1 → keycycle-0.3.2}/keycycle/core/utils.py

@@ -323,16 +323,14 @@ def load_api_keys(
     except ValueError:
         raise ValueError(f"'{num_keys_var}' must be an integer, got: {num_keys_raw}")
 
-    # A key fleet isn't always numbered contiguously from 1..N -- a retired
-    # or never-issued key can leave a gap (e.g. a provider's *_API_KEY_25
-    # through *_API_KEY_36 missing while 1..24 and 37..46 are live, because
-    # NUM_{PROVIDER} was set once and never reconciled after keys were added
-    # or dropped). Scanning `range(1, expected_count + 1)` either crashes on
-    # the first missing index or silently caps the fleet at expected_count,
-    # even when more keys exist above that number. Instead, scan every
-    # {PROVIDER}_API_KEY_<index> variable that actually exists, in whatever
-    # order the indices fall, and use all of them -- NUM_{PROVIDER} becomes
-    # an expectation to warn against, not a hard loop bound.
+    # NUM_{PROVIDER} is AUTHORITATIVE (0.3.2, reverting 0.3.1's scan-all):
+    # the fleet convention is that the first NUM indices (sorted ascending)
+    # are the sanctioned live keys, and keys parked at higher indices beyond
+    # a numbering gap are dead or spare on purpose -- loading them would put
+    # known-bad keys back into rotation. Gaps INSIDE the sanctioned range
+    # are tolerated (a retired key's index can be missing); the loader takes
+    # the first NUM indices that actually exist and warns if it comes up
+    # short, but never loads past NUM keys.
     key_pattern = re.compile(rf"^{re.escape(provider_upper)}_API_KEY_(\d+)$")
     found: Dict[int, str] = {}
     for env_name, value in os.environ.items():
@@ -343,11 +341,20 @@ def load_api_keys(
     if not found:
         raise ValueError(f"Missing API key: {provider_upper}_API_KEY_1")
 
-    indices = sorted(found)
-    if len(indices) != expected_count:
+    all_indices = sorted(found)
+    indices = all_indices[:expected_count]
+    excluded = all_indices[expected_count:]
+    if excluded:
+        logging.getLogger(__name__).info(
+            "%s: %s=%d -- using the first %d key indices %s; excluding %d "
+            "parked key(s) at indices %s (dead/spare by convention).",
+            provider_upper, num_keys_var, expected_count, len(indices), indices,
+            len(excluded), excluded,
+        )
+    if len(indices) < expected_count:
         logging.getLogger(__name__).warning(
-            "%s: found %d API key(s) (indices %s) but %s=%d -- numbering has "
-            "a gap or is stale. Using all %d key(s) actually found.",
+            "%s: only %d API key(s) found (indices %s) but %s=%d -- the "
+            "declared count is stale. Using the %d key(s) actually found.",
             provider_upper, len(indices), indices, num_keys_var, expected_count,
             len(indices),
         )

{keycycle-0.3.1 → keycycle-0.3.2}/keycycle.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keycycle
-Version: 0.3.1
+Version: 0.3.2
 Summary: A thread-safe key rotation and rate limiting manager for API keys.
 Author-email: William Jin <jinwilliam.jin@gmail.com>
 Classifier: Programming Language :: Python :: 3

{keycycle-0.3.1 → keycycle-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keycycle"
-version = "0.3.1"
+version = "0.3.2"
 authors = [
   { name="William Jin", email="jinwilliam.jin@gmail.com" },
 ]

{keycycle-0.3.1 → keycycle-0.3.2}/tests/test_multi_client_wrapper.py

@@ -331,25 +331,37 @@ class TestLoadApiKeysStatic(unittest.TestCase):
         self.assertIn("Missing API key", str(ctx.exception))
 
     @patch.dict(os.environ, {
-        # A real-world fleet whose NUM_ counter went stale after keys were
-        # added/retired: 24 keys, then a gap, then 10 more (mirrors William's
-        # GROQ fleet: 1..24 live, 25..36 retired, 37..46 re-issued).
+        # The fleet convention (0.3.2): the first NUM indices are the
+        # sanctioned live keys; keys parked at higher indices beyond a gap
+        # are dead or spare ON PURPOSE (mirrors William's GROQ fleet:
+        # 1..24 live, 37..46 parked dead). NUM is authoritative.
         "NUM_GAPPY": "24",
         **{f"GAPPY_API_KEY_{i}": f"key-{i}" for i in range(1, 25)},
         **{f"GAPPY_API_KEY_{i}": f"key-{i}" for i in range(37, 47)},
     })
     @patch('keycycle.multi_client_wrapper.load_dotenv')
-    def test_load_keys_tolerates_numbering_gap(self, mock_dotenv):
-        """A gap in the index sequence should not crash or truncate the fleet."""
+    def test_load_keys_num_caps_out_parked_keys(self, mock_dotenv):
+        """Only the first NUM sorted indices load; parked keys stay out."""
         keys = MultiClientWrapper.load_api_keys("gappy")
 
-        # All 34 keys are found (both sides of the gap), even though
-        # NUM_GAPPY only claims 24 -- the env var is a hint, not a cap.
-        self.assertEqual(len(keys), 34)
+        self.assertEqual(len(keys), 24)
         self.assertEqual(keys[0], "key-1")
-        self.assertEqual(keys[23], "key-24")
-        self.assertEqual(keys[24], "key-37")
-        self.assertEqual(keys[-1], "key-46")
+        self.assertEqual(keys[-1], "key-24")
+
+    @patch.dict(os.environ, {
+        # A gap INSIDE the sanctioned range is tolerated: index 2 retired,
+        # NUM still says 3, so the loader takes the first 3 that exist
+        # (1, 3, 4) rather than crashing or stopping at the gap.
+        "NUM_HOLEY": "3",
+        "HOLEY_API_KEY_1": "key-1",
+        "HOLEY_API_KEY_3": "key-3",
+        "HOLEY_API_KEY_4": "key-4",
+        "HOLEY_API_KEY_9": "key-9",
+    })
+    @patch('keycycle.multi_client_wrapper.load_dotenv')
+    def test_load_keys_tolerates_gap_inside_sanctioned_range(self, mock_dotenv):
+        keys = MultiClientWrapper.load_api_keys("holey")
+        self.assertEqual(keys, ["key-1", "key-3", "key-4"])
 
     @patch.dict(os.environ, {
         "NUM_SPARSE": "5",