httpx-limiter 0.1.0__tar.gz → 0.2.0__tar.gz

{httpx_limiter-0.1.0 → httpx_limiter-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: httpx-limiter
-Version: 0.1.0
+Version: 0.2.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
@@ -8,8 +8,9 @@ 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
 Author-email: "Moritz E. Beber" <midnighter@posteo.net>
-License: Apache-2.0
-Keywords: httpx,limiter,rate-limit
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: httpx,leaky bucket,limiter,rate-limit
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Environment :: Web Environment
 Classifier: Framework :: AsyncIO
@@ -25,8 +26,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: aiolimiter~=1.2
 Requires-Dist: httpx~=0.25
-Requires-Dist: limiter~=0.5
 Description-Content-Type: text/markdown
 
 # HTTPX Limiter
@@ -41,7 +42,8 @@ _A lightweight package that provides rate-limited httpx transports._
 
 ## Installation
 
-The package is published on [PyPI](). Install it, for example, with
+The package is published on [PyPI](https://pypi.org/project/httpx-limiter/).
+Install it, for example, with
 
 ```sh
 pip install httpx-limiter
@@ -49,22 +51,23 @@ pip install httpx-limiter
 
 ## Usage
 
-For situations when you need to make a large number of asynchronous request with a
-controlled number of requests per time, you can apply rate limiting to an HTTPX client
-using the provided transport. If you want to be able to make ten requests per second,
-for example, use the following:
+For situations when you need to make a large number of asynchronous request with
+a controlled number of requests per unit time, you can apply rate limiting to an
+HTTPX client using the provided transport. If you want to be able to make ten
+requests per second, for example, use the following:
 
 ```python
 import httpx
-from httpx_limiter import AsyncRateLimitedTransport
+from httpx_limiter import AsyncRateLimitedTransport, Rate
 
-async with httpx.AsyncClient(
-    transport=AsyncRateLimitedTransport.create(rate=10, capacity=10),
-) as client:
-    ...
+async def main():
+    async with httpx.AsyncClient(
+        transport=AsyncRateLimitedTransport.create(rate=Rate.create(magnitude=10)),
+    ) as client:
+        response = await client.get("https://httpbin.org")
 ```
 
 ## Copyright
 
-- Copyright © 2024 Moritz E. Beber.
+- Copyright © 2024,2025 Moritz E. Beber.
 - Free software distributed under the [Apache Software License 2.0](./LICENSE).

{httpx_limiter-0.1.0 → httpx_limiter-0.2.0}/README.md

@@ -10,7 +10,8 @@ _A lightweight package that provides rate-limited httpx transports._
 
 ## Installation
 
-The package is published on [PyPI](). Install it, for example, with
+The package is published on [PyPI](https://pypi.org/project/httpx-limiter/).
+Install it, for example, with
 
 ```sh
 pip install httpx-limiter
@@ -18,22 +19,23 @@ pip install httpx-limiter
 
 ## Usage
 
-For situations when you need to make a large number of asynchronous request with a
-controlled number of requests per time, you can apply rate limiting to an HTTPX client
-using the provided transport. If you want to be able to make ten requests per second,
-for example, use the following:
+For situations when you need to make a large number of asynchronous request with
+a controlled number of requests per unit time, you can apply rate limiting to an
+HTTPX client using the provided transport. If you want to be able to make ten
+requests per second, for example, use the following:
 
 ```python
 import httpx
-from httpx_limiter import AsyncRateLimitedTransport
+from httpx_limiter import AsyncRateLimitedTransport, Rate
 
-async with httpx.AsyncClient(
-    transport=AsyncRateLimitedTransport.create(rate=10, capacity=10),
-) as client:
-    ...
+async def main():
+    async with httpx.AsyncClient(
+        transport=AsyncRateLimitedTransport.create(rate=Rate.create(magnitude=10)),
+    ) as client:
+        response = await client.get("https://httpbin.org")
 ```
 
 ## Copyright
 
-- Copyright © 2024 Moritz E. Beber.
+- Copyright © 2024,2025 Moritz E. Beber.
 - Free software distributed under the [Apache Software License 2.0](./LICENSE).

{httpx_limiter-0.1.0 → httpx_limiter-0.2.0}/pyproject.toml

@@ -41,10 +41,11 @@ keywords = [
     "httpx",
     "limiter",
     "rate-limit",
+    "leaky bucket",
 ]
 dependencies = [
     "httpx ~=0.25",
-    "limiter ~=0.5",
+    "aiolimiter ~=1.2",
 ]
 
 [project.urls]
@@ -103,8 +104,6 @@ ignore = [
     "D407",  # 'Missing dashed underline after section' ignored because Google style docstrings don't underline.
     "ANN002",  # 'Missing type annotation for {*args} in method'.
     "ANN003",  # 'Missing type annotation for {*kwargs} in method'.
-    "ANN101",  # 'Missing type annotation for {self} in method'.
-    "ANN102",  # 'Missing type annotation for {cls} in classmethod'.
 ]
 exclude = [
     "src/httpx_limiter/_version.py",
@@ -130,7 +129,7 @@ known-first-party = ["src", "httpx_limiter"]
 lines-after-imports = 2
 
 [tool.pydoclint]
-style = "google"  # TODO: Other styles are possible here, like 'numpy'
+style = "google"
 arg-type-hints-in-docstring = false
 check-return-types = false
 check-yield-types = false
@@ -173,20 +172,21 @@ extra-dependencies = [
     "pytest",
     "pytest-httpx",
     "pytest-watcher",
+    "ruff",
 ]
 path = ".venv"
 
 [tool.hatch.envs.style]
 description = """Check the style of the codebase."""
 dependencies = [
-    "pydoclint",
+    "pydoclint ~=0.6",
     "ruff",
 ]
 detached = true
 installer = "uv"
 
 [tool.hatch.envs.style.scripts]
-docstrings = "pydoclint"
+docstrings = ["pydoclint src", "pydoclint tests"]
 code = "ruff check {args}"
 format = "ruff format {args}"
 check = ["docstrings", "code"]
@@ -221,33 +221,50 @@ extra-dependencies = [
 build = "mkdocs build {args:--clean --strict}"
 serve = "mkdocs serve {args}"
 
-[tool.hatch.envs.install]
-description = """Test the installation the package."""
-dependencies = [
-    "pip",
-    "twine",
-]
-detached = true
+#[tool.hatch.envs.install]
+#description = """Test the installation the package."""
+#dependencies = [
+#    "pip",
+#    "twine",
+#]
+#detached = true
+
+#[tool.hatch.envs.install.scripts]
+#check = [
+#    "pip check",
+#    "hatch build {args:--clean}",
+#    "twine check dist/*",
+#]
 
-[tool.hatch.envs.install.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",
 ]
 
-[tool.hatch.envs.test]
-description = """Run the test suite."""
+[[tool.hatch.envs.unit-tests.matrix]]
+python = ["3.10", "3.11", "3.12", "3.13"]
+
+[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",
+    # TODO: Use behave in future.
     "pytest",
     "pytest-cov",
     "pytest-httpx",
     "pytest-raises",
 ]
 
-[[tool.hatch.envs.test.matrix]]
+[[tool.hatch.envs.acceptance-tests.matrix]]
 python = ["3.10", "3.11", "3.12", "3.13"]
 
-[tool.hatch.envs.test.scripts]
-run = "pytest {args:--cov=httpx_limiter --cov-report=term-missing}"
+[tool.hatch.envs.acceptance-tests.scripts]
+run = "pytest {args:--cov=httpx_limiter --cov-report=term-missing} {root}/tests/acceptance"

{httpx_limiter-0.1.0 → httpx_limiter-0.2.0}/src/httpx_limiter/__init__.py

@@ -15,4 +15,5 @@
 
 """Provide top level symbols."""
 
+from .rate import Number, Rate
 from .async_rate_limited_transport import AsyncRateLimitedTransport

{httpx_limiter-0.1.0 → httpx_limiter-0.2.0}/src/httpx_limiter/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)

{httpx_limiter-0.1.0 → httpx_limiter-0.2.0}/src/httpx_limiter/async_rate_limited_transport.py

@@ -17,8 +17,14 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 import httpx
-from limiter import Limiter, Tokens
+from aiolimiter import AsyncLimiter
+
+
+if TYPE_CHECKING:
+    from .rate import Rate
 
 
 class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
@@ -26,7 +32,7 @@ class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
     Define the asynchronous rate-limited transport.
 
     This transport consists of a composed transport for handling requests and an
-    implementation of a token bucket algorithm in order to rate-limit the number of
+    implementation of a leaky bucket algorithm in order to rate-limit the number of
     requests.
 
     """
@@ -34,7 +40,7 @@ class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
     def __init__(
         self,
         *,
-        limiter: Limiter,
+        limiter: AsyncLimiter,
         transport: httpx.AsyncBaseTransport,
         **kwargs,
     ) -> None:
@@ -46,20 +52,18 @@ class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
     def create(
         cls,
         *,
-        rate: Tokens,
-        capacity: Tokens,
+        rate: Rate,
         **kwargs: dict,
     ) -> AsyncRateLimitedTransport:
         """
-        Create an instance of asynchronous limited transport.
+        Create an instance of asynchronous rate-limited transport.
 
         This factory method constructs the instance with an underlying
         `httpx.AsyncHTTPTransport`.
         That transport is passed any additional keyword arguments.
 
         Args:
-            rate: The refresh rate per second for bucket tokens.
-            capacity: The maximum number of tokens the bucket can contain.
+            rate: The maximum rate per interval at which bucket capacity is restored.
             **kwargs: Additional keyword arguments are used in the construction of an
                 `httpx.AsyncHTTPTransport`.
 
@@ -68,7 +72,10 @@ class AsyncRateLimitedTransport(httpx.AsyncBaseTransport):
 
         """
         return cls(
-            limiter=Limiter(rate=rate, capacity=capacity),
+            limiter=AsyncLimiter(
+                max_rate=rate.magnitude,
+                time_period=rate.in_seconds(),
+            ),
             transport=httpx.AsyncHTTPTransport(**kwargs),  # type: ignore[arg-type]
         )
 

httpx_limiter-0.2.0/src/httpx_limiter/rate.py

@@ -0,0 +1,45 @@
+# 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 a definition of a rate."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import NamedTuple
+
+
+Number = float | int
+
+
+class Rate(NamedTuple):
+    """Define the rate."""
+
+    magnitude: float
+    duration: timedelta
+
+    @classmethod
+    def create(cls, magnitude: Number = 1, duration: timedelta | Number = 1) -> Rate:
+        """Create a rate."""
+        magnitude = float(magnitude)
+
+        if not isinstance(duration, timedelta):
+            duration = timedelta(seconds=float(duration))
+
+        return cls(magnitude=magnitude, duration=duration)
+
+    def in_seconds(self) -> float:
+        """Return the duration in unit seconds."""
+        return self.duration.total_seconds()