Reference API

The following classes are exposed to the user:

• Rate
• AbstractAsyncLimiter
• AsyncRateLimitedTransport
• AbstractRateLimiterRepository
• AsyncMultiRateLimitedTransport
• AiolimiterAsyncLimiter
• PyrateAsyncLimiter

httpx_limiter

Provide top level symbols.

Rate

Bases: NamedTuple

Define the rate.

duration: timedelta instance-attribute

magnitude: int instance-attribute

create(magnitude: int = 1, duration: timedelta | Number = 1) -> Rate classmethod

Create a rate.

in_milliseconds() -> int

Return the duration in unit milliseconds.

in_seconds() -> float

Return the duration in unit seconds.

AbstractAsyncLimiter

Bases: ABC

Define an abstract base class for asynchronous rate limiters.

This interface dictates that all asynchronous rate limiters shall implement the context manager protocol.

__aenter__() -> AbstractAsyncLimiter abstractmethod async

Acquire a rate limit token upon entering the asynchronous context.

__aexit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) -> None abstractmethod async

Exit the asynchronous context.

AsyncRateLimitedTransport

Bases: AsyncBaseTransport

Define the asynchronous rate-limited transport.

This transport consists of a composed transport for handling requests and an implementation of a leaky bucket algorithm in order to rate-limit the number of requests.

__init__(*, limiter: AbstractAsyncLimiter, transport: httpx.AsyncBaseTransport, **kwargs: dict[str, object]) -> None

create(limiter: AbstractAsyncLimiter, **kwargs: Unpack[HTTPXAsyncHTTPTransportKeywordArguments]) -> AsyncRateLimitedTransport classmethod

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.

Parameters:

Name	Type	Description	Default
limiter	AbstractAsyncLimiter	A concrete instance of an asynchronous limiter.	required
**kwargs	Unpack[HTTPXAsyncHTTPTransportKeywordArguments]	Additional keyword arguments are used in the construction of an httpx.AsyncHTTPTransport.	{}

Returns:

Type	Description
AsyncRateLimitedTransport	A default instance of the class created from the given arguments.

handle_async_request(request: httpx.Request) -> httpx.Response async

Handle an asynchronous request with rate limiting.

AbstractRateLimiterRepository

Bases: ABC

Define the abstract repository for rate limiters.

This abstract base class provides a framework for managing rate limiters based on HTTP requests. It maintains a cache of rate limiters and provides methods to retrieve request-specific identifiers, rates, and limiters.

Subclasses must implement methods to determine how requests are identified and what rate limits should be applied to them.

Methods:

Name	Description
get_identifier	Return a request-specific identifier.
get_rates	Return one or more request-specific rates.
get	Return a request-specific rate limiter.

__init__(**kwargs: dict[str, object]) -> None

create(request: httpx.Request) -> AbstractAsyncLimiter abstractmethod

Return a request-specific rate limiter.

get(request: httpx.Request) -> AbstractAsyncLimiter

Return a request-specific rate limiter.

get_identifier(request: httpx.Request) -> str abstractmethod

Return a request-specific identifier.

AsyncMultiRateLimitedTransport

Bases: AsyncBaseTransport

Define the asynchronous multiple rate-limited transport.

This transport consists of a composed transport for handling requests and a repository for rate limiters that are selected based on the request.

__init__(*, repository: AbstractRateLimiterRepository, transport: httpx.AsyncBaseTransport, **kwargs: dict[str, object]) -> None

create(*, repository: AbstractRateLimiterRepository, **kwargs: Unpack[HTTPXAsyncHTTPTransportKeywordArguments]) -> AsyncMultiRateLimitedTransport classmethod

Create an instance of an asynchronous multiple rate-limited transport.

This factory method constructs the instance with an underlying httpx.AsyncHTTPTransport. That transport is passed any additional keyword arguments.

Parameters:

Name	Type	Description	Default
repository	AbstractRateLimiterRepository	The repository to use for rate limiters.	required
**kwargs	Unpack[HTTPXAsyncHTTPTransportKeywordArguments]	Additional keyword arguments are used in the construction of an httpx.AsyncHTTPTransport.	{}

Returns:

Type	Description
AsyncMultiRateLimitedTransport	A default instance of the class created from the given arguments.

handle_async_request(request: httpx.Request) -> httpx.Response async

Handle an asynchronous request with rate limiting.

httpx_limiter.aiolimiter

Provide aiolimiter-based rate limiting functionality.

AiolimiterAsyncLimiter

Bases: AbstractAsyncLimiter

Define an asynchronous limiter that composes the aiolimiter AsyncLimiter.

This class encapsulates the creation and configuration of an aiolimiter AsyncLimiter with appropriate settings.

Parameters:

Name	Type	Description	Default
limiter	AsyncLimiter	An instance of an aiolimiter AsyncLimiter.	required
**kwargs	dict[str, object]	Additional keyword arguments for the parent classes.	{}

__aenter__() -> AiolimiterAsyncLimiter async

Acquire a token upon entering the asynchronous context.

__aexit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) -> None async

Exit the asynchronous context.

__init__(*, limiter: AsyncLimiter, **kwargs: dict[str, object]) -> None

create(rate: Rate) -> AiolimiterAsyncLimiter classmethod

Create an instance of AiolimiterAsyncLimiter.

Note: aiolimiter only supports a single rate limit, unlike pyrate-limiter which supports multiple rates.

httpx_limiter.pyrate

Provide pyrate-based rate limiting functionality.

PyrateAsyncLimiter

Bases: AbstractAsyncLimiter

Define an asynchronous limiter that composes the pyrate limiter.

This class encapsulates the creation and configuration of a pyrate-limiter Limiter with appropriate async bucket wrapper and settings.

Parameters:

Name	Type	Description	Default
limiter	Limiter	An instance of an asynchronous pyrate limiter.	required
**kwargs	dict[str, object]	Additional keyword arguments for the parent classes.	{}

__aenter__() -> PyrateAsyncLimiter async

Acquire a token upon entering the asynchronous context.

__aexit__(_exc_type: type[BaseException] | None, _exc_val: BaseException | None, _exc_tb: TracebackType | None) -> None async

Exit the asynchronous context.

__init__(*, limiter: Limiter, **kwargs: dict[str, object]) -> None

create(*rates: Rate, **kwargs: Unpack[PyRateLimiterKeywordArguments]) -> PyrateAsyncLimiter classmethod

Create an instance of PyrateAsyncLimiter.