httpx-limiter 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpx-limiter
-Version: 0.4.0
+Version: 0.5.0
 Summary: A lightweight package that provides rate-limited httpx transports.
 Project-URL: Homepage, https://github.com/Midnighter/httpx-limiter
 Project-URL: Documentation, https://httpx-limiter.readthedocs.io
@@ -27,8 +27,11 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: httpx~=0.25
-Requires-Dist: pyrate-limiter~=3.9
 Requires-Dist: typing-extensions~=4.6; python_version < '3.11'
+Provides-Extra: aiolimiter
+Requires-Dist: aiolimiter~=1.2; extra == 'aiolimiter'
+Provides-Extra: pyrate
+Requires-Dist: pyrate-limiter~=3.9; extra == 'pyrate'
 Description-Content-Type: text/markdown
 
 # HTTPX Limiter
@@ -43,33 +46,89 @@ _A lightweight package that provides rate-limited httpx transports._
 
 ## Installation
 
-The package is published on [PyPI](https://pypi.org/project/httpx-limiter/).
-Install it, for example, with
+The package is published on [PyPI](https://pypi.org/project/httpx-limiter/). Install it,
+for example, with the aiolimiter backend.
 
 ```sh
-pip install httpx-limiter
+pip install 'httpx-limiter[aiolimiter]'
+```
+
+There is also a pyrate-limiter backend available.
+
+```sh
+pip install 'httpx-limiter[pyrate]'
+```
+
+## Rate Limiter Backends
+
+This package provides two different asynchronous rate limiter implementations to choose
+from:
+
+1. [aiolimiter](https://aiolimiter.readthedocs.io)
+2. [pyrate-limiter](https://pyratelimiter.readthedocs.io)
+
+> [!IMPORTANT]
+> While both implementations fulfill similar purposes, there are significant differences
+> between them. Please read the descriptions below to make an informed decision about
+> which one best suits your needs.
+
+### 1. aiolimiter
+
+-   **Single rate limit only**: Supports only one rate limit at a time
+-   **Lightweight**: Minimal dependencies and simpler configuration
+-   **Linear token refresh rate**: As an example, if you set a rate of 2 per second,
+    roughly one token will be added every 500 milliseconds
+
+```python
+from httpx_limiter.aiolimiter import AiolimiterAsyncLimiter
+
+limiter = AiolimiterAsyncLimiter.create(Rate.create(magnitude=20))
+```
+
+### 2. pyrate-limiter
+
+-   **Multiple rate limits**: Support for multiple concurrent rate limits, for example,
+    10 requests per second _and_ 100 requests per minute
+-   **Flexible configuration**: Comprehensive configuration options
+-   **Multiprocessing dependency**: Current implementation depends on `multiprocessing`
+    which may not be available in all environments, such as pyodide
+-   **Stepwise token refresh rate**: As an example, if you set a rate of 2 per second,
+    two token will be added every second
+
+```python
+from httpx_limiter.pyrate import PyrateAsyncLimiter
+
+# Single rate limit
+limiter = PyrateAsyncLimiter.create(Rate.create(magnitude=20))
+
+# Multiple rate limits
+limiter = PyrateAsyncLimiter.create(
+    Rate.create(magnitude=10),  # 10 per second
+    Rate.create(magnitude=100, duration=60),  # 100 per minute
+)
 ```
 
 ## Tutorial
 
-You can limit the number of requests made by an HTTPX client using the
-transports provided in this package. That is useful in situations when you need
-to make a large number of asynchronous requests against endpoints that implement
-a rate limit.
+You can limit the number of requests made by an HTTPX client using the transports
+provided in this package. That is useful in situations when you need to make a large
+number of asynchronous requests against endpoints that implement a rate limit.
 
 ### Single Rate Limit
 
-The simplest use case is to apply a single rate limit to all requests. If you
-want to be able to make twenty requests per second, for example, use the
-following code:
+The simplest use case is to apply a single rate limit to all requests. If you want to be
+able to make twenty requests per second, for example, use the following code:
 
 ```python
 import httpx
 from httpx_limiter import AsyncRateLimitedTransport, Rate
+from httpx_limiter.pyrate import PyrateAsyncLimiter
 
 async def main():
+    limiter = PyrateAsyncLimiter.create(Rate.create(magnitude=20))
+
     async with httpx.AsyncClient(
-        transport=AsyncRateLimitedTransport.create(Rate.create(magnitude=20)),
+        transport=AsyncRateLimitedTransport.create(limiter=limiter),
     ) as client:
         response = await client.get("https://httpbin.org")
 ```
@@ -90,11 +149,11 @@ async def main():
 
 ### Multiple Rate Limits
 
-For more advanced use cases, you can apply different rate limits based on a
-concrete implementation of the `AbstractRateLimiterRepository`. There are two
-relevant methods that both get passed the current request. One method needs to
-identify which rate limit to apply, and the other method sets the rate limit
-itself. See the following example:
+For more advanced use cases, you can apply different rate limits based on a concrete
+implementation of the `AbstractRateLimiterRepository`. There are two relevant methods
+that both get passed the current request. One method needs to return an identifier for
+which rate limiter to choose, and the other method creates a rate limiter. See the
+following example:
 
 ```python
 import httpx
@@ -103,6 +162,7 @@ from httpx_limiter import (
     AsyncMultiRateLimitedTransport,
     Rate
 )
+from httpx_limiter.aiolimiter import AiolimiterAsyncLimiter
 
 class DomainBasedRateLimiterRepository(AbstractRateLimiterRepository):
     """Apply different rate limits based on the domain being requested."""
@@ -111,9 +171,9 @@ class DomainBasedRateLimiterRepository(AbstractRateLimiterRepository):
         """Return the domain as the identifier for rate limiting."""
         return request.url.host
 
-    def get_rate(self, request: httpx.Request) -> Rate:
-        """Apply the same, but independent rate limit to each domain."""
-        return Rate.create(magnitude=25)
+    def create(self, request: httpx.Request) -> AiolimiterAsyncLimiter:
+        """Create a rate limiter for the domain."""
+        return AiolimiterAsyncLimiter.create(Rate.create(magnitude=25))
 
 client = httpx.AsyncClient(
     transport=AsyncMultiRateLimitedTransport.create(
@@ -128,27 +188,27 @@ client = httpx.AsyncClient(
 
 ```python
 from datetime import datetime, timezone
-from collections.abc import Sequence
 
 import httpx
 from httpx_limiter import AbstractRateLimiterRepository, Rate
+from httpx_limiter.pyrate import PyrateAsyncLimiter
 
 class DayNightRateLimiterRepository(AbstractRateLimiterRepository):
     """Apply different rate limits based on the time of day."""
 
-    def get_identifier(self, _: httpx.Request) -> str:
+    def get_identifier(self, request: httpx.Request) -> str:
         """Identify whether it is currently day or night."""
         if 6 <= datetime.now(tz=timezone.utc).hour < 18:
             return "day"
 
         return "night"
 
-    def get_rates(self, _: httpx.Request) -> Sequence[Rate]:
-        """Apply different rate limits during the day or night."""
-        if self.get_identifier(_) == "day":
-            return [Rate.create(magnitude=10)]
+    def create(self, request: httpx.Request) -> PyrateAsyncLimiter:
+        """Create a rate limiter based on the time of day."""
+        if self.get_identifier(request) == "day":
+            return PyrateAsyncLimiter.create(Rate.create(magnitude=10))
 
-        return [Rate.create(magnitude=100)]
+        return PyrateAsyncLimiter.create(Rate.create(magnitude=100))
 ```
 
 ## Copyright

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

@@ -10,33 +10,89 @@ _A lightweight package that provides rate-limited httpx transports._
 
 ## Installation
 
-The package is published on [PyPI](https://pypi.org/project/httpx-limiter/).
-Install it, for example, with
+The package is published on [PyPI](https://pypi.org/project/httpx-limiter/). Install it,
+for example, with the aiolimiter backend.
 
 ```sh
-pip install httpx-limiter
+pip install 'httpx-limiter[aiolimiter]'
+```
+
+There is also a pyrate-limiter backend available.
+
+```sh
+pip install 'httpx-limiter[pyrate]'
+```
+
+## Rate Limiter Backends
+
+This package provides two different asynchronous rate limiter implementations to choose
+from:
+
+1. [aiolimiter](https://aiolimiter.readthedocs.io)
+2. [pyrate-limiter](https://pyratelimiter.readthedocs.io)
+
+> [!IMPORTANT]
+> While both implementations fulfill similar purposes, there are significant differences
+> between them. Please read the descriptions below to make an informed decision about
+> which one best suits your needs.
+
+### 1. aiolimiter
+
+-   **Single rate limit only**: Supports only one rate limit at a time
+-   **Lightweight**: Minimal dependencies and simpler configuration
+-   **Linear token refresh rate**: As an example, if you set a rate of 2 per second,
+    roughly one token will be added every 500 milliseconds
+
+```python
+from httpx_limiter.aiolimiter import AiolimiterAsyncLimiter
+
+limiter = AiolimiterAsyncLimiter.create(Rate.create(magnitude=20))
+```
+
+### 2. pyrate-limiter
+
+-   **Multiple rate limits**: Support for multiple concurrent rate limits, for example,
+    10 requests per second _and_ 100 requests per minute
+-   **Flexible configuration**: Comprehensive configuration options
+-   **Multiprocessing dependency**: Current implementation depends on `multiprocessing`
+    which may not be available in all environments, such as pyodide
+-   **Stepwise token refresh rate**: As an example, if you set a rate of 2 per second,
+    two token will be added every second
+
+```python
+from httpx_limiter.pyrate import PyrateAsyncLimiter
+
+# Single rate limit
+limiter = PyrateAsyncLimiter.create(Rate.create(magnitude=20))
+
+# Multiple rate limits
+limiter = PyrateAsyncLimiter.create(
+    Rate.create(magnitude=10),  # 10 per second
+    Rate.create(magnitude=100, duration=60),  # 100 per minute
+)
 ```
 
 ## Tutorial
 
-You can limit the number of requests made by an HTTPX client using the
-transports provided in this package. That is useful in situations when you need
-to make a large number of asynchronous requests against endpoints that implement
-a rate limit.
+You can limit the number of requests made by an HTTPX client using the transports
+provided in this package. That is useful in situations when you need to make a large
+number of asynchronous requests against endpoints that implement a rate limit.
 
 ### Single Rate Limit
 
-The simplest use case is to apply a single rate limit to all requests. If you
-want to be able to make twenty requests per second, for example, use the
-following code:
+The simplest use case is to apply a single rate limit to all requests. If you want to be
+able to make twenty requests per second, for example, use the following code:
 
 ```python
 import httpx
 from httpx_limiter import AsyncRateLimitedTransport, Rate
+from httpx_limiter.pyrate import PyrateAsyncLimiter
 
 async def main():
+    limiter = PyrateAsyncLimiter.create(Rate.create(magnitude=20))
+
     async with httpx.AsyncClient(
-        transport=AsyncRateLimitedTransport.create(Rate.create(magnitude=20)),
+        transport=AsyncRateLimitedTransport.create(limiter=limiter),
     ) as client:
         response = await client.get("https://httpbin.org")
 ```
@@ -57,11 +113,11 @@ async def main():
 
 ### Multiple Rate Limits
 
-For more advanced use cases, you can apply different rate limits based on a
-concrete implementation of the `AbstractRateLimiterRepository`. There are two
-relevant methods that both get passed the current request. One method needs to
-identify which rate limit to apply, and the other method sets the rate limit
-itself. See the following example:
+For more advanced use cases, you can apply different rate limits based on a concrete
+implementation of the `AbstractRateLimiterRepository`. There are two relevant methods
+that both get passed the current request. One method needs to return an identifier for
+which rate limiter to choose, and the other method creates a rate limiter. See the
+following example:
 
 ```python
 import httpx
@@ -70,6 +126,7 @@ from httpx_limiter import (
     AsyncMultiRateLimitedTransport,
     Rate
 )
+from httpx_limiter.aiolimiter import AiolimiterAsyncLimiter
 
 class DomainBasedRateLimiterRepository(AbstractRateLimiterRepository):
     """Apply different rate limits based on the domain being requested."""
@@ -78,9 +135,9 @@ class DomainBasedRateLimiterRepository(AbstractRateLimiterRepository):
         """Return the domain as the identifier for rate limiting."""
         return request.url.host
 
-    def get_rate(self, request: httpx.Request) -> Rate:
-        """Apply the same, but independent rate limit to each domain."""
-        return Rate.create(magnitude=25)
+    def create(self, request: httpx.Request) -> AiolimiterAsyncLimiter:
+        """Create a rate limiter for the domain."""
+        return AiolimiterAsyncLimiter.create(Rate.create(magnitude=25))
 
 client = httpx.AsyncClient(
     transport=AsyncMultiRateLimitedTransport.create(
@@ -95,27 +152,27 @@ client = httpx.AsyncClient(
 
 ```python
 from datetime import datetime, timezone
-from collections.abc import Sequence
 
 import httpx
 from httpx_limiter import AbstractRateLimiterRepository, Rate
+from httpx_limiter.pyrate import PyrateAsyncLimiter
 
 class DayNightRateLimiterRepository(AbstractRateLimiterRepository):
     """Apply different rate limits based on the time of day."""
 
-    def get_identifier(self, _: httpx.Request) -> str:
+    def get_identifier(self, request: httpx.Request) -> str:
         """Identify whether it is currently day or night."""
         if 6 <= datetime.now(tz=timezone.utc).hour < 18:
             return "day"
 
         return "night"
 
-    def get_rates(self, _: httpx.Request) -> Sequence[Rate]:
-        """Apply different rate limits during the day or night."""
-        if self.get_identifier(_) == "day":
-            return [Rate.create(magnitude=10)]
+    def create(self, request: httpx.Request) -> PyrateAsyncLimiter:
+        """Create a rate limiter based on the time of day."""
+        if self.get_identifier(request) == "day":
+            return PyrateAsyncLimiter.create(Rate.create(magnitude=10))
 
-        return [Rate.create(magnitude=100)]
+        return PyrateAsyncLimiter.create(Rate.create(magnitude=100))
 ```
 
 ## Copyright

{httpx_limiter-0.4.0 → httpx_limiter-0.5.0}/pyproject.toml

@@ -38,7 +38,6 @@ classifiers = [
 keywords = ["httpx", "limiter", "rate-limit", "leaky bucket"]
 dependencies = [
     "httpx ~=0.25",
-    "pyrate-limiter ~=3.9",
     "typing-extensions ~=4.6; python_version < '3.11'",
 ]
 
@@ -49,6 +48,10 @@ Documentation = "https://httpx-limiter.readthedocs.io"
 "Bug Tracker" = "https://github.com/Midnighter/httpx-limiter/issues"
 Download = "https://pypi.org/project/httpx-limiter/#files"
 
+[project.optional-dependencies]
+aiolimiter = ["aiolimiter ~=1.2"]
+pyrate = ["pyrate-limiter ~=3.9"]
+
 ################################################################################
 # Tool Configuration
 ################################################################################
@@ -109,6 +112,10 @@ exclude = ["src/httpx_limiter/_version.py"]
     "ANN201",  # 'Missing type annotation for {return}' ignored because all tests return `None`.
     "PLR2004", # Magic numbers are okay in tests.
 ]
+"tests/pyodide/**/*.py" = [
+    "PLC0415", # We explicitly need imports inside function and ignore the '`import` should be at the top-level of a file' rule.
+    "I001",    # 'Import block is un-sorted or un-formatted' ignored because we may have to import in a particular, not-alphabetical order.
+]
 
 [tool.ruff.lint.isort]
 case-sensitive = true
@@ -144,6 +151,7 @@ ignore_missing_imports = true
 
 [tool.hatch.envs.default]
 installer = "uv"
+features = ["aiolimiter", "pyrate"]
 
 [tool.hatch.envs.dev]
 description = """Development environment."""
@@ -180,7 +188,7 @@ check = ["pip-audit"]
 
 [tool.hatch.envs.types]
 description = """Check the static types of the codebase."""
-dependencies = ["mypy"]
+extra-dependencies = ["mypy"]
 
 [tool.hatch.envs.types.scripts]
 check = "mypy src/httpx_limiter"
@@ -204,6 +212,7 @@ description = """Test the source and wheel distribution of the package."""
 dependencies = ["pip", "twine"]
 detached = true
 installer = "uv"
+builder = true
 
 [tool.hatch.envs.distribution.scripts]
 check = ["pip check", "hatch build {args:--clean}", "twine check dist/*"]

{httpx_limiter-0.4.0 → httpx_limiter-0.5.0}/src/httpx_limiter/__init__.py

@@ -17,7 +17,7 @@
 
 from .types import HTTPXAsyncHTTPTransportKeywordArguments
 from .rate import Number, Rate
-from .async_limiter import AsyncLimiter, PyRateLimiterKeywordArguments
+from .abstract_async_limiter import AbstractAsyncLimiter
 from .async_rate_limited_transport import AsyncRateLimitedTransport
 from .abstract_rate_limiter_repository import AbstractRateLimiterRepository
 from .async_multi_rate_limited_transport import AsyncMultiRateLimitedTransport

{httpx_limiter-0.4.0 → httpx_limiter-0.5.0}/src/httpx_limiter/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

httpx_limiter-0.5.0/src/httpx_limiter/abstract_async_limiter.py

@@ -0,0 +1,48 @@
+# Copyright (c) 2025 Moritz E. Beber
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+
+"""Provide an abstract base class for asynchronous rate limiters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:  # pragma: no cover
+    from types import TracebackType
+
+
+class AbstractAsyncLimiter(ABC):
+    """
+    Define an abstract base class for asynchronous rate limiters.
+
+    This interface dictates that all asynchronous rate limiters shall implement the
+    context manager protocol.
+
+    """
+
+    @abstractmethod
+    async def __aenter__(self) -> AbstractAsyncLimiter:
+        """Acquire a rate limit token upon entering the asynchronous context."""
+
+    @abstractmethod
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the asynchronous context."""

{httpx_limiter-0.4.0 → httpx_limiter-0.5.0}/src/httpx_limiter/abstract_rate_limiter_repository.py

@@ -16,12 +16,10 @@
 """Provide an abstract repository for rate limiters."""
 
 from abc import ABC, abstractmethod
-from collections.abc import Sequence
 
 import httpx
 
-from .async_limiter import AsyncLimiter, PyRateLimiterKeywordArguments
-from .rate import Rate
+from .abstract_async_limiter import AbstractAsyncLimiter
 
 
 class AbstractRateLimiterRepository(ABC):
@@ -44,31 +42,21 @@ class AbstractRateLimiterRepository(ABC):
 
     def __init__(self, **kwargs: dict[str, object]) -> None:
         super().__init__(**kwargs)
-        self._limiters: dict[str, AsyncLimiter] = {}
+        self._limiters: dict[str, AbstractAsyncLimiter] = {}
 
     @abstractmethod
     def get_identifier(self, request: httpx.Request) -> str:
         """Return a request-specific identifier."""
 
     @abstractmethod
-    def get_rates(self, request: httpx.Request) -> Sequence[Rate]:
-        """Return one or more request-specific rates."""
-
-    def _get_limiter_kwargs(
-        self,
-        request: httpx.Request,  # noqa: ARG002
-    ) -> PyRateLimiterKeywordArguments:
-        """Return the keyword arguments for creating a rate limiter."""
-        return {}
+    def create(self, request: httpx.Request) -> AbstractAsyncLimiter:
+        """Return a request-specific rate limiter."""
 
-    def get(self, request: httpx.Request) -> AsyncLimiter:
+    def get(self, request: httpx.Request) -> AbstractAsyncLimiter:
         """Return a request-specific rate limiter."""
         identifier = self.get_identifier(request)
 
         if identifier not in self._limiters:
-            self._limiters[identifier] = AsyncLimiter.create(
-                *self.get_rates(request),
-                **self._get_limiter_kwargs(request),
-            )
+            self._limiters[identifier] = self.create(request)
 
         return self._limiters[identifier]

httpx_limiter-0.5.0/src/httpx_limiter/aiolimiter/__init__.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2025 Moritz E. Beber
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+
+"""Provide aiolimiter-based rate limiting functionality."""
+
+from .aiolimiter_async_limiter import AiolimiterAsyncLimiter

httpx_limiter-0.5.0/src/httpx_limiter/aiolimiter/aiolimiter_async_limiter.py

@@ -0,0 +1,76 @@
+# Copyright (c) 2025 Moritz E. Beber
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+
+"""Provide an asynchronous rate-limited transport using aiolimiter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from aiolimiter import AsyncLimiter
+
+from httpx_limiter import AbstractAsyncLimiter
+
+
+if TYPE_CHECKING:  # pragma: no cover
+    from types import TracebackType
+
+    from httpx_limiter.rate import Rate
+
+
+class AiolimiterAsyncLimiter(AbstractAsyncLimiter):
+    """
+    Define an asynchronous limiter that composes the aiolimiter AsyncLimiter.
+
+    This class encapsulates the creation and configuration of an aiolimiter
+    AsyncLimiter with appropriate settings.
+
+    Args:
+        limiter: An instance of an aiolimiter AsyncLimiter.
+        **kwargs: Additional keyword arguments for the parent classes.
+
+    """
+
+    def __init__(self, *, limiter: AsyncLimiter, **kwargs: dict[str, object]) -> None:
+        super().__init__(**kwargs)
+        self._limiter = limiter
+
+    @classmethod
+    def create(cls, rate: Rate) -> AiolimiterAsyncLimiter:
+        """
+        Create an instance of AiolimiterAsyncLimiter.
+
+        Note: aiolimiter only supports a single rate limit, unlike pyrate-limiter
+        which supports multiple rates.
+        """
+        limiter = AsyncLimiter(
+            max_rate=rate.magnitude,
+            time_period=rate.in_seconds(),
+        )
+        return cls(limiter=limiter)
+
+    async def __aenter__(self) -> AiolimiterAsyncLimiter:  # noqa: PYI034
+        """Acquire a token upon entering the asynchronous context."""
+        await self._limiter.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the asynchronous context."""
+        await self._limiter.__aexit__(exc_type=exc_type, exc=exc_val, tb=exc_tb)

{httpx_limiter-0.4.0 → httpx_limiter-0.5.0}/src/httpx_limiter/async_rate_limited_transport.py

@@ -28,11 +28,9 @@ else:
 
 import httpx
 
-from .async_limiter import AsyncLimiter
-
 
 if TYPE_CHECKING:  # pragma: no cover
-    from .rate import Rate
+    from .abstract_async_limiter import AbstractAsyncLimiter
     from .types import HTTPXAsyncHTTPTransportKeywordArguments
 
 
@@ -49,7 +47,7 @@ class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
     def __init__(
         self,
         *,
-        limiter: AsyncLimiter,
+        limiter: AbstractAsyncLimiter,
         transport: httpx.AsyncBaseTransport,
         **kwargs: dict[str, object],
     ) -> None:
@@ -60,7 +58,7 @@ class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
     @classmethod
     def create(
         cls,
-        *rates: Rate,
+        limiter: AbstractAsyncLimiter,
         **kwargs: Unpack[HTTPXAsyncHTTPTransportKeywordArguments],
     ) -> AsyncRateLimitedTransport:
         """
@@ -71,7 +69,7 @@ class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
         That transport is passed any additional keyword arguments.
 
         Args:
-            *rates: One or more rate limits to apply.
+            limiter: A concrete instance of an asynchronous limiter.
             **kwargs: Additional keyword arguments are used in the construction of an
                 `httpx.AsyncHTTPTransport`.
 
@@ -80,8 +78,8 @@ class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
 
         """
         return cls(
-            limiter=AsyncLimiter.create(*rates),
-            transport=httpx.AsyncHTTPTransport(**kwargs),  # type: ignore[arg-type]
+            limiter=limiter,
+            transport=httpx.AsyncHTTPTransport(**kwargs),
         )
 
     async def handle_async_request(

httpx_limiter-0.5.0/src/httpx_limiter/pyrate/__init__.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2025 Moritz E. Beber
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+
+"""Provide pyrate-based rate limiting functionality."""
+
+from .pyrate_async_limiter import PyrateAsyncLimiter, PyRateLimiterKeywordArguments

httpx_limiter-0.4.0/src/httpx_limiter/async_limiter.py → httpx_limiter-0.5.0/src/httpx_limiter/pyrate/pyrate_async_limiter.py

@@ -37,11 +37,13 @@ from pyrate_limiter import (
 )
 from pyrate_limiter import Rate as PyRate
 
+from httpx_limiter import AbstractAsyncLimiter
+
 
 if TYPE_CHECKING:  # pragma: no cover
     from types import TracebackType
 
-    from .rate import Rate
+    from httpx_limiter.rate import Rate
 
 
 class PyRateLimiterKeywordArguments(TypedDict, total=False):
@@ -54,7 +56,7 @@ class PyRateLimiterKeywordArguments(TypedDict, total=False):
     buffer_ms: int
 
 
-class AsyncLimiter:
+class PyrateAsyncLimiter(AbstractAsyncLimiter):
     """
     Define an asynchronous limiter that composes the pyrate limiter.
 
@@ -76,8 +78,8 @@ class AsyncLimiter:
         cls,
         *rates: Rate,
         **kwargs: Unpack[PyRateLimiterKeywordArguments],
-    ) -> AsyncLimiter:
-        """Create an instance of AsyncLimiter."""
+    ) -> PyrateAsyncLimiter:
+        """Create an instance of PyrateAsyncLimiter."""
         if not rates:
             msg = "At least one rate must be provided."
             raise ValueError(msg)
@@ -94,17 +96,18 @@ class AsyncLimiter:
             )
             raise ValueError(msg)
 
+        # Cast kwargs to proper types for internal use
         limiter = Limiter(
             argument=BucketAsyncWrapper(InMemoryBucket(rate_limits)),
             clock=kwargs.get("clock", TimeAsyncClock()),
             raise_when_fail=kwargs.get("raise_when_fail", False),
             max_delay=kwargs.get("max_delay", Duration.HOUR),
-            retry_until_max_delay=kwargs.get("retry_until_max_delay", False),
+            retry_until_max_delay=kwargs.get("retry_until_max_delay", True),
             buffer_ms=kwargs.get("buffer_ms", 50),
         )
         return cls(limiter=limiter)
 
-    async def __aenter__(self) -> AsyncLimiter:  # noqa: PYI034
+    async def __aenter__(self) -> PyrateAsyncLimiter:  # noqa: PYI034
         """Acquire a token upon entering the asynchronous context."""
         # Keep trying to acquire, let timeouts be handled externally.
         while not (await self._limiter.try_acquire_async("httpx-limiter")):

{httpx_limiter-0.4.0 → httpx_limiter-0.5.0}/src/httpx_limiter/rate.py

@@ -48,6 +48,10 @@ class Rate(NamedTuple):
 
         return cls(magnitude=magnitude, duration=duration)
 
+    def in_seconds(self) -> float:
+        """Return the duration in unit seconds."""
+        return self.duration.total_seconds()
+
     def in_milliseconds(self) -> int:
         """Return the duration in unit milliseconds."""
         return int(self.duration.total_seconds() * 1_000)

{httpx_limiter-0.4.0 → httpx_limiter-0.5.0}/src/httpx_limiter/types.py

@@ -16,23 +16,38 @@
 """Provide additional type definitions."""
 
 import ssl
-import typing
-from typing import TypedDict
+from collections.abc import Iterable
+from typing import TypeAlias, TypedDict
 
 import httpx
 
 
+# Fallback for Pyodide HTTPX. See: https://github.com/Midnighter/httpx-limiter/pull/10#issuecomment-3241566927
+SocketOption: TypeAlias = (
+    tuple[int, int, int]
+    | tuple[int, int, bytes | bytearray]
+    | tuple[int, int, None, int]
+)
+
+# We redefine the following types from httpx._types to avoid a dependency on the
+# private module. It would be better if HTTPX exposed these types publicly, but
+# they are unlikely to change often. Thus we consider it acceptable to redefine
+# them here for type hinting purposes.
+CertTypes: TypeAlias = str | tuple[str, str] | tuple[str, str, str]
+ProxyTypes: TypeAlias = httpx.URL | str | httpx.Proxy
+
+
 class HTTPXAsyncHTTPTransportKeywordArguments(TypedDict, total=False):
     """Keyword arguments for the httpx.AsyncHTTPTransport constructor."""
 
     verify: ssl.SSLContext | str | bool
-    cert: httpx._types.CertTypes | None
+    cert: CertTypes | None
     trust_env: bool
     http1: bool
     http2: bool
-    limits: httpx._config.Limits
-    proxy: httpx._types.ProxyTypes | None
+    limits: httpx.Limits
+    proxy: ProxyTypes | None
     uds: str | None
     local_address: str | None
     retries: int
-    socket_options: typing.Iterable[httpx._transports.default.SOCKET_OPTION] | None
+    socket_options: Iterable[SocketOption] | None