blitz-api-py 0.4.0__tar.gz → 0.5.0__tar.gz

{blitz_api_py-0.4.0 → blitz_api_py-0.5.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0](https://github.com/api-blitz/blitz-api-py/compare/v0.4.0...v0.5.0) (2026-06-18)
+
+
+### Features
+
+* scope client-side rate limiting per endpoint ([#13](https://github.com/api-blitz/blitz-api-py/issues/13)) ([de5308b](https://github.com/api-blitz/blitz-api-py/commit/de5308b6995edc68dd1e43a8554296b7de095df2))
+
 ## [0.4.0](https://github.com/api-blitz/blitz-api-py/compare/v0.3.0...v0.4.0) (2026-06-17)
 
 

{blitz_api_py-0.4.0 → blitz_api_py-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blitz-api-py
-Version: 0.4.0
+Version: 0.5.0
 Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
 Project-URL: Homepage, https://blitz-api.ai
 Project-URL: Documentation, https://docs.blitz-api.ai
@@ -258,10 +258,13 @@ client = BlitzAPI(
 ```
 
 The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
-in any rolling second — so a single client instance stays under the API's limit (5 req/s
-by default; check your key's limit via
-`client.account.key_info().max_requests_per_seconds`). Across multiple processes you may
-still hit `429` — the retry path handles that.
+in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
+`.phone`) is throttled independently, mirroring the API's own limit, which is also per
+endpoint (5 req/s by default; check yours via
+`client.account.key_info().max_requests_per_seconds`). A single client instance therefore
+stays under the limit on every endpoint, so a burst on one never blocks another. Across
+multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
+path handles that.
 
 Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
 endpoint needs longer than the client default:

{blitz_api_py-0.4.0 → blitz_api_py-0.5.0}/README.md

@@ -227,10 +227,13 @@ client = BlitzAPI(
 ```
 
 The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
-in any rolling second — so a single client instance stays under the API's limit (5 req/s
-by default; check your key's limit via
-`client.account.key_info().max_requests_per_seconds`). Across multiple processes you may
-still hit `429` — the retry path handles that.
+in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
+`.phone`) is throttled independently, mirroring the API's own limit, which is also per
+endpoint (5 req/s by default; check yours via
+`client.account.key_info().max_requests_per_seconds`). A single client instance therefore
+stays under the limit on every endpoint, so a burst on one never blocks another. Across
+multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
+path handles that.
 
 Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
 endpoint needs longer than the client default:

{blitz_api_py-0.4.0 → blitz_api_py-0.5.0}/src/blitz_api/_client_async.py

@@ -50,13 +50,34 @@ class AsyncBlitzAPI(BaseClient):
             )
         self._http_client = http_client or httpx.AsyncClient(timeout=timeout)
         self._owns_http_client = http_client is None
-        self._rate_limiter = AsyncRateLimiter(rate_limit_rps)
+        self._rate_limit_rps = rate_limit_rps
+        # One limiter per endpoint path so each endpoint's rate limit is tracked
+        # independently (e.g. ``.email`` and ``.phone`` do not share a budget). Built
+        # lazily in ``_limiter_for`` on first use of each path.
+        self._rate_limiters: dict[str, AsyncRateLimiter] = {}
         if sleep is None:
             import asyncio
 
             sleep = asyncio.sleep
         self._sleep = sleep
 
+    def _limiter_for(self, path: str) -> AsyncRateLimiter:
+        """Return the per-endpoint limiter for ``path``, creating it on first use.
+
+        Each endpoint path gets its own sliding window so its rate limit is tracked
+        independently of every other endpoint.
+        """
+        limiter = self._rate_limiters.get(path)
+        if limiter is None:
+            # ``setdefault`` keeps concurrent first-callers on the same instance; any
+            # extra limiter built in a race is harmlessly discarded. Thread the client's
+            # ``sleep`` through so a custom/fake sleep injected for tests also drives the
+            # limiter's throttle wait, not just the retry backoff.
+            limiter = self._rate_limiters.setdefault(
+                path, AsyncRateLimiter(self._rate_limit_rps, sleep=self._sleep)
+            )
+        return limiter
+
     async def _request(
         self,
         method: str,
@@ -72,7 +93,7 @@ class AsyncBlitzAPI(BaseClient):
 
         attempt = 0
         while True:
-            await self._rate_limiter.acquire()
+            await self._limiter_for(path).acquire()
             try:
                 if timeout is None:
                     response = await self._http_client.request(

{blitz_api_py-0.4.0 → blitz_api_py-0.5.0}/src/blitz_api/_client_sync.py

@@ -52,13 +52,34 @@ class BlitzAPI(BaseClient):
             )
         self._http_client = http_client or httpx.Client(timeout=timeout)
         self._owns_http_client = http_client is None
-        self._rate_limiter = RateLimiter(rate_limit_rps)
+        self._rate_limit_rps = rate_limit_rps
+        # One limiter per endpoint path so each endpoint's rate limit is tracked
+        # independently (e.g. ``.email`` and ``.phone`` do not share a budget). Built
+        # lazily in ``_limiter_for`` on first use of each path.
+        self._rate_limiters: dict[str, RateLimiter] = {}
         if sleep is None:
             import time
 
             sleep = time.sleep
         self._sleep = sleep
 
+    def _limiter_for(self, path: str) -> RateLimiter:
+        """Return the per-endpoint limiter for ``path``, creating it on first use.
+
+        Each endpoint path gets its own sliding window so its rate limit is tracked
+        independently of every other endpoint.
+        """
+        limiter = self._rate_limiters.get(path)
+        if limiter is None:
+            # ``setdefault`` keeps concurrent first-callers on the same instance; any
+            # extra limiter built in a race is harmlessly discarded. Thread the client's
+            # ``sleep`` through so a custom/fake sleep injected for tests also drives the
+            # limiter's throttle wait, not just the retry backoff.
+            limiter = self._rate_limiters.setdefault(
+                path, RateLimiter(self._rate_limit_rps, sleep=self._sleep)
+            )
+        return limiter
+
     def _request(
         self,
         method: str,
@@ -74,7 +95,7 @@ class BlitzAPI(BaseClient):
 
         attempt = 0
         while True:
-            self._rate_limiter.acquire()
+            self._limiter_for(path).acquire()
             try:
                 if timeout is None:
                     response = self._http_client.request(

{blitz_api_py-0.4.0 → blitz_api_py-0.5.0}/src/blitz_api/_rate_limit_async.py

@@ -1,9 +1,11 @@
 """Client-side sliding-window rate limiter (async source; sync twin generated).
 
-The API enforces a per-key request rate (5 req/s by default). This limiter throttles
-outgoing requests *before* they are sent so a single client instance stays under the
-limit proactively; the server-side 429 retry path is the backstop for bursts across
-processes.
+The API enforces a per-endpoint request rate (5 req/s by default). This limiter throttles
+outgoing requests *before* they are sent. The client holds one limiter **per endpoint
+path** (see ``_client_async.py``), so each endpoint is throttled to ``rps`` independently,
+mirroring the server's per-endpoint budget; a single client instance therefore stays under
+the limit on every endpoint on its own. The server-side 429 retry path is the backstop for
+bursts across processes, which share the same per-endpoint budget.
 
 The algorithm is a sliding window: at most ``rps`` requests may begin in any rolling
 one-second window. This matches the Blitz docs ("max 5 requests per 1000 ms") and the

{blitz_api_py-0.4.0 → blitz_api_py-0.5.0}/src/blitz_api/_rate_limit_sync.py

@@ -2,10 +2,12 @@
 # Do not edit by hand — edit the async source and run `python scripts/gen_sync.py`.
 """Client-side sliding-window rate limiter (async source; sync twin generated).
 
-The API enforces a per-key request rate (5 req/s by default). This limiter throttles
-outgoing requests *before* they are sent so a single client instance stays under the
-limit proactively; the server-side 429 retry path is the backstop for bursts across
-processes.
+The API enforces a per-endpoint request rate (5 req/s by default). This limiter throttles
+outgoing requests *before* they are sent. The client holds one limiter **per endpoint
+path** (see ``_client_async.py``), so each endpoint is throttled to ``rps`` independently,
+mirroring the server's per-endpoint budget; a single client instance therefore stays under
+the limit on every endpoint on its own. The server-side 429 retry path is the backstop for
+bursts across processes, which share the same per-endpoint budget.
 
 The algorithm is a sliding window: at most ``rps`` requests may begin in any rolling
 one-second window. This matches the Blitz docs ("max 5 requests per 1000 ms") and the

blitz_api_py-0.5.0/src/blitz_api/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"  # x-release-please-version

blitz_api_py-0.4.0/src/blitz_api/_version.py

@@ -1 +0,0 @@
-__version__ = "0.4.0"  # x-release-please-version