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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: httpx-limiter
-Version: 0.4.0
+Version: 0.6.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
+Project-URL: Documentation, https://midnighter.github.io/httpx-limiter/
 Project-URL: Source Code, https://github.com/Midnighter/httpx-limiter
 Project-URL: Bug Tracker, https://github.com/Midnighter/httpx-limiter/issues
 Project-URL: Download, https://pypi.org/project/httpx-limiter/#files
@@ -13,7 +13,6 @@ License-File: LICENSE
 Keywords: httpx,leaky bucket,limiter,rate-limit
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Environment :: Web Environment
-Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
@@ -23,12 +22,16 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 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~=4.0; extra == 'pyrate'
 Description-Content-Type: text/markdown
 
 # HTTPX Limiter
@@ -43,33 +46,92 @@ _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 import Rate
+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 import Rate
+from httpx_limiter.pyrate import PyrateAsyncLimiter
+
+async def main():
+    # 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 +152,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 +165,8 @@ 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,15 +175,19 @@ 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(
-        repository=DomainBasedRateLimiterRepository(),
-    ),
-)
+
+async def main():
+    async with httpx.AsyncClient(
+        transport=AsyncMultiRateLimitedTransport.create(
+            repository=DomainBasedRateLimiterRepository(),
+        ),
+    ) as client:
+        # Use the client instance as you normally would.
+        pass
 ```
 
 > [!TIP]
@@ -128,27 +196,28 @@ 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.6.0}/README.md

@@ -10,33 +10,92 @@ _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 import Rate
+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 import Rate
+from httpx_limiter.pyrate import PyrateAsyncLimiter
+
+async def main():
+    # 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 +116,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 +129,8 @@ 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,15 +139,19 @@ 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(
-        repository=DomainBasedRateLimiterRepository(),
-    ),
-)
+
+async def main():
+    async with httpx.AsyncClient(
+        transport=AsyncMultiRateLimitedTransport.create(
+            repository=DomainBasedRateLimiterRepository(),
+        ),
+    ) as client:
+        # Use the client instance as you normally would.
+        pass
 ```
 
 > [!TIP]
@@ -95,27 +160,28 @@ 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.6.0}/pyproject.toml

@@ -22,7 +22,6 @@ requires-python = ">=3.10"
 classifiers = [
     "Development Status :: 2 - Pre-Alpha",
     "Environment :: Web Environment",
-    "Framework :: AsyncIO",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Natural Language :: English",
@@ -32,23 +31,38 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Internet :: WWW/HTTP",
     "Typing :: Typed",
 ]
 keywords = ["httpx", "limiter", "rate-limit", "leaky bucket"]
 dependencies = [
     "httpx ~=0.25",
-    "pyrate-limiter ~=3.9",
     "typing-extensions ~=4.6; python_version < '3.11'",
 ]
 
 [project.urls]
 Homepage = "https://github.com/Midnighter/httpx-limiter"
-Documentation = "https://httpx-limiter.readthedocs.io"
+Documentation = "https://midnighter.github.io/httpx-limiter/"
 "Source Code" = "https://github.com/Midnighter/httpx-limiter"
 "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 ~=4.0"]
+
+[dependency-groups]
+style = ["pydoclint", "ruff"]
+types = ["mypy", "ty"]
+docs = [
+    "mkdocs-material ~=9.5",
+    "mkdocstrings[python] ~=1.0",
+    "mkdocs-awesome-pages-plugin ~=2.9",
+    "mike ~=2.1",
+]
+tests = ["anyio", "pytest", "pytest-cov", "pytest-httpx", "pytest-raises"]
+
 ################################################################################
 # Tool Configuration
 ################################################################################
@@ -109,6 +123,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
@@ -122,38 +140,36 @@ check-return-types = false
 check-yield-types = false
 exclude = "_version.py"
 
-# TODO: Adjust mypy configuration.
-#[tool.mypy]
-#plugins = [
-#    "pydantic.mypy",
-#]
-
-# Stop mypy from complaining about missing types from imports.
-[[tool.mypy.overrides]]
-module = ["limiter"]
-ignore_missing_imports = true
-
-#[tool.pydantic-mypy]
-#init_forbid_extra = true
-#init_typed = true
-#warn_required_dynamic_aliases = true
-
 ################################################################################
 # Hatch Environments
 ################################################################################
 
+[tool.hatch.env]
+requires = ["hatch-pip-compile"]
+
 [tool.hatch.envs.default]
-installer = "uv"
+description = """
+Base environment with default configuration values.
+
+All environments inheriting from the default also inherit the configuration values set
+here.
+"""
+type = "pip-compile"
+lock-filename = "requirements/requirements-{env_name}.txt"
+pip-compile-constraint = "dev"
+pip-compile-hashes = true
+pip-compile-resolver = "uv"
+pip-compile-installer = "uv"
+features = ["aiolimiter", "pyrate"]
+
+[tool.hatch.envs.no-install]
+description = """A base environment for use cases that do not install the project."""
+skip-install = true
+features = []
 
 [tool.hatch.envs.dev]
 description = """Development environment."""
-extra-dependencies = [
-    "anyio",
-    "pytest",
-    "pytest-httpx",
-    "pytest-watcher",
-    "ruff",
-]
+dependency-groups = ["style", "types", "docs", "tests"]
 
 [tool.hatch.envs.dev.env-vars]
 PYTHONDEVMODE = "1"
@@ -161,14 +177,14 @@ PYTHONASYNCIODEBUG = "1"
 
 [tool.hatch.envs.style]
 description = """Check the style of the codebase."""
-dependencies = ["pydoclint", "ruff"]
-detached = true
-installer = "uv"
+template = "no-install"
+dependency-groups = ["style"]
 
 [tool.hatch.envs.style.scripts]
 docstrings = ["pydoclint src", "pydoclint tests"]
 code = "ruff check {args}"
 format = "ruff format {args}"
+fix = "ruff check --fix {args}"
 check = ["docstrings", "code"]
 
 [tool.hatch.envs.audit]
@@ -180,19 +196,14 @@ check = ["pip-audit"]
 
 [tool.hatch.envs.types]
 description = """Check the static types of the codebase."""
-dependencies = ["mypy"]
+dependency-groups = ["types"]
 
 [tool.hatch.envs.types.scripts]
-check = "mypy src/httpx_limiter"
+check = ["mypy src/httpx_limiter", "ty check src/httpx_limiter"]
 
 [tool.hatch.envs.docs]
 description = """Build or serve the documentation."""
-extra-dependencies = [
-    "mkdocs-material ~=9.5",
-    "mkdocstrings[python] ~=0.24",
-    "mkdocs-awesome-pages-plugin ~=2.9",
-    "mike ~=2.1",
-]
+dependency-groups = ["docs"]
 
 [tool.hatch.envs.docs.scripts]
 build = "mkdocs build {args:--clean --strict}"
@@ -201,49 +212,52 @@ deploy = "mike deploy {args}"
 
 [tool.hatch.envs.distribution]
 description = """Test the source and wheel distribution of the package."""
+template = "no-install"
 dependencies = ["pip", "twine"]
-detached = true
-installer = "uv"
+builder = true
 
 [tool.hatch.envs.distribution.scripts]
 check = ["pip check", "hatch build {args:--clean}", "twine check dist/*"]
 
 [tool.hatch.envs.unit-tests]
 description = """Run the unit tests."""
-extra-dependencies = [
-    "anyio",
-    "pytest",
-    "pytest-cov",
-    "pytest-httpx",
-    "pytest-raises",
-]
+dependency-groups = ["tests"]
 
 [tool.hatch.envs.unit-tests.env-vars]
 PYTHONDEVMODE = "1"
 PYTHONASYNCIODEBUG = "1"
 
 [[tool.hatch.envs.unit-tests.matrix]]
-python = ["3.10", "3.11", "3.12", "3.13"]
+python = ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
 [tool.hatch.envs.unit-tests.scripts]
 run = "pytest {args:--cov=httpx_limiter --cov-report=term-missing} {root}/tests/unit"
 
 [tool.hatch.envs.acceptance-tests]
 description = """Run the acceptance tests."""
-extra-dependencies = [
-    "anyio",
-    "pytest",
-    "pytest-cov",
-    "pytest-httpx",
-    "pytest-raises",
-]
+dependency-groups = ["tests"]
 
 [tool.hatch.envs.acceptance-tests.env-vars]
 PYTHONDEVMODE = "1"
 PYTHONASYNCIODEBUG = "1"
 
 [[tool.hatch.envs.acceptance-tests.matrix]]
-python = ["3.10", "3.11", "3.12", "3.13"]
+python = ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
 [tool.hatch.envs.acceptance-tests.scripts]
 run = "pytest {args:--cov=httpx_limiter --cov-report=term-missing} {root}/tests/acceptance"
+
+[tool.hatch.envs.documentation-tests]
+description = """Run the documentation tests."""
+dependency-groups = ["tests"]
+extra-dependencies = ["mktestdocs", "httpx-tenacity ~=0.1"]
+
+[tool.hatch.envs.documentation-tests.env-vars]
+PYTHONDEVMODE = "1"
+PYTHONASYNCIODEBUG = "1"
+
+[[tool.hatch.envs.documentation-tests.matrix]]
+python = ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+[tool.hatch.envs.documentation-tests.scripts]
+run = "pytest {args:--cov=httpx_limiter --cov-report=term-missing} {root}/tests/documentation"

{httpx_limiter-0.4.0 → httpx_limiter-0.6.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.6.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.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
 
 __commit_id__ = commit_id = None

httpx_limiter-0.6.0/src/httpx_limiter/abstract_async_limiter.py

@@ -0,0 +1,47 @@
+# 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."""
+
+    async def __aexit__(  # noqa: B027
+        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.6.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.6.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.6.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.6.0}/src/httpx_limiter/async_multi_rate_limited_transport.py

@@ -79,7 +79,7 @@ class AsyncMultiRateLimitedTransport(httpx.AsyncBaseTransport):
         """
         return cls(
             repository=repository,
-            transport=httpx.AsyncHTTPTransport(**kwargs),  # type: ignore[arg-type]
+            transport=httpx.AsyncHTTPTransport(**kwargs),
         )
 
     async def handle_async_request(

{httpx_limiter-0.4.0 → httpx_limiter-0.6.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.6.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.6.0/src/httpx_limiter/pyrate/pyrate_async_limiter.py

@@ -27,34 +27,27 @@ else:
     from typing import Unpack
 
 from pyrate_limiter import (
-    AbstractClock,
     BucketAsyncWrapper,
-    Duration,
     InMemoryBucket,
     Limiter,
-    TimeAsyncClock,
     validate_rate_list,
 )
 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
+if TYPE_CHECKING:  # pragma: no cover
+    from httpx_limiter.rate import Rate
 
 
 class PyRateLimiterKeywordArguments(TypedDict, total=False):
     """Keyword arguments for the pyrate limiter."""
 
-    clock: AbstractClock
-    raise_when_fail: bool
-    max_delay: int | Duration | None
-    retry_until_max_delay: bool
     buffer_ms: int
 
 
-class AsyncLimiter:
+class PyrateAsyncLimiter(AbstractAsyncLimiter):
     """
     Define an asynchronous limiter that composes the pyrate limiter.
 
@@ -76,8 +69,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)
@@ -95,27 +88,12 @@ class AsyncLimiter:
             raise ValueError(msg)
 
         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),
+            BucketAsyncWrapper(InMemoryBucket(rate_limits)),
             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")):
-            pass  # pragma: no cover
-
+        await self._limiter.try_acquire_async(__name__)
         return self
-
-    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.6.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.6.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