RateLimiter

The main rate limiter classes for async and sync usage.

RateLimiter (Async)

RateLimiter

RateLimiter(name='limiter', region=None, endpoint_url=None, stack_options=None, failure_mode=FAIL_CLOSED, auto_update=True, strict_version=True, skip_version_check=False)

Async rate limiter backed by DynamoDB.

Implements token bucket algorithm with support for: - Multiple limits per entity/resource - Two-level hierarchy (parent/child entities) - Cascade mode (consume from entity + parent) - Stored limit configs - Usage analytics

Example

limiter = RateLimiter( name="my-app", # Creates ZAEL-my-app resources region="us-east-1", stack_options=StackOptions(), )

Parameters:

Name	Type	Description	Default
name	str	Resource identifier (e.g., 'my-app'). Will be prefixed with 'ZAEL-' automatically. Default: 'limiter' (creates 'ZAEL-limiter' resources)	'limiter'
region	str | None	AWS region	None
endpoint_url	str | None	DynamoDB endpoint URL (for local development)	None
stack_options	StackOptions | None	Desired infrastructure state (None = connect only, don't manage)	None
failure_mode	FailureMode	Behavior when DynamoDB is unavailable	FAIL_CLOSED
auto_update	bool	Auto-update Lambda when version mismatch detected	True
strict_version	bool	Fail if version mismatch (when auto_update is False)	True
skip_version_check	bool	Skip all version checks (dangerous)	False

name property

name

The resource identifier (with ZAEL- prefix).

close async

close()

Close the underlying connections.

create_entity async

create_entity(entity_id, name=None, parent_id=None, metadata=None)

Create a new entity.

Parameters:

Name	Type	Description	Default
entity_id	str	Unique identifier for the entity	required
name	str | None	Human-readable name (defaults to entity_id)	None
parent_id	str | None	Parent entity ID (None for root/project entities)	None
metadata	dict[str, str] | None	Additional metadata to store	None

Returns:

Type	Description
Entity	The created Entity

Raises:

Type	Description
EntityExistsError	If entity already exists

get_entity async

get_entity(entity_id)

Get an entity by ID.

delete_entity async

delete_entity(entity_id)

Delete an entity and all its related data.

get_children async

get_children(parent_id)

Get all children of a parent entity.

acquire async

acquire(entity_id, resource, limits, consume, cascade=False, use_stored_limits=False, failure_mode=None)

Acquire rate limit capacity.

Parameters:

Name	Type	Description	Default
entity_id	str	Entity to acquire capacity for	required
resource	str	Resource being accessed (e.g., "gpt-4")	required
limits	list[Limit]	Default limits to apply	required
consume	dict[str, int]	Amounts to consume by limit name	required
cascade	bool	If True, also consume from parent entity	False
use_stored_limits	bool	If True, use stored limits if available	False
failure_mode	FailureMode | None	Override default failure mode	None

Yields:

Type	Description
AsyncIterator[Lease]	Lease for managing additional consumption

Raises:

Type	Description
RateLimitExceeded	If any limit would be exceeded
RateLimiterUnavailable	If DynamoDB unavailable and FAIL_CLOSED

available async

available(entity_id, resource, limits, use_stored_limits=False)

Check available capacity without consuming.

Returns minimum available across entity (and parent if cascade). Can return negative values if bucket is in debt.

Parameters:

Name	Type	Description	Default
entity_id	str	Entity to check	required
resource	str	Resource to check	required
limits	list[Limit]	Default limits	required
use_stored_limits	bool	Use stored limits if available	False

Returns:

Type	Description
dict[str, int]	Dict mapping limit_name -> available tokens

time_until_available async

time_until_available(entity_id, resource, limits, needed, use_stored_limits=False)

Calculate seconds until requested capacity is available.

Parameters:

Name	Type	Description	Default
entity_id	str	Entity to check	required
resource	str	Resource to check	required
limits	list[Limit]	Default limits	required
needed	dict[str, int]	Required amounts by limit name	required
use_stored_limits	bool	Use stored limits if available	False

Returns:

Type	Description
float	Seconds until available (0.0 if already available)

set_limits async

set_limits(entity_id, limits, resource=DEFAULT_RESOURCE)

Store limit configs for an entity.

Parameters:

Name	Type	Description	Default
entity_id	str	Entity to set limits for	required
limits	list[Limit]	Limits to store	required
resource	str	Resource these limits apply to (or default)	DEFAULT_RESOURCE

get_limits async

get_limits(entity_id, resource=DEFAULT_RESOURCE)

Get stored limit configs for an entity.

Parameters:

Name	Type	Description	Default
entity_id	str	Entity to get limits for	required
resource	str	Resource to get limits for	DEFAULT_RESOURCE

Returns:

Type	Description
list[Limit]	List of stored limits (empty if none)

delete_limits async

delete_limits(entity_id, resource=DEFAULT_RESOURCE)

Delete stored limit configs for an entity.

Parameters:

Name	Type	Description	Default
entity_id	str	Entity to delete limits for	required
resource	str	Resource to delete limits for	DEFAULT_RESOURCE

get_resource_capacity async

get_resource_capacity(resource, limit_name, parents_only=False)

Get aggregated capacity for a resource across all entities.

Parameters:

Name	Type	Description	Default
resource	str	Resource to query	required
limit_name	str	Limit name to query	required
parents_only	bool	If True, only include parent entities	False

Returns:

Type	Description
ResourceCapacity	ResourceCapacity with aggregated data

create_stack async

create_stack(stack_options=None)

Create CloudFormation stack for infrastructure.

Parameters:

Name	Type	Description	Default
stack_options	StackOptions | None	Stack configuration	None

Returns:

Type	Description
dict[str, Any]	Dict with stack_id, stack_name, and status

Raises:

Type	Description
StackCreationError	If stack creation fails

delete_stack async

delete_stack()

Delete the CloudFormation stack and all associated resources.

This method permanently removes the CloudFormation stack, including:

• DynamoDB table and all stored data
• Lambda aggregator function (if deployed)
• IAM roles and CloudWatch log groups
• All other stack resources

The method waits for deletion to complete before returning. If the stack doesn't exist, no error is raised.

Raises:

Type	Description
StackCreationError	If deletion fails (e.g., permission denied, resources in use, or CloudFormation service error)

Example

Cleanup after integration testing::

limiter = RateLimiter(
    name="test-limits",
    region="us-east-1",
    stack_options=StackOptions(),
)

async with limiter:
    # Run tests...
    pass

# Clean up infrastructure
await limiter.delete_stack()

Warning

This operation is irreversible. All rate limit state, entity data, and usage history will be permanently deleted.

SyncRateLimiter

SyncRateLimiter

SyncRateLimiter(name='limiter', region=None, endpoint_url=None, stack_options=None, failure_mode=FAIL_CLOSED, auto_update=True, strict_version=True, skip_version_check=False)

Synchronous rate limiter backed by DynamoDB.

Wraps RateLimiter, running async operations in an event loop.

Example

limiter = SyncRateLimiter( name="my-app", # Creates ZAEL-my-app resources region="us-east-1", stack_options=StackOptions(), )

close

close()

Close the underlying connections.

create_entity

create_entity(entity_id, name=None, parent_id=None, metadata=None)

Create a new entity.

get_entity

get_entity(entity_id)

Get an entity by ID.

delete_entity

delete_entity(entity_id)

Delete an entity and all its related data.

get_children

get_children(parent_id)

Get all children of a parent entity.

acquire

acquire(entity_id, resource, limits, consume, cascade=False, use_stored_limits=False, failure_mode=None)

Acquire rate limit capacity (synchronous).

available

available(entity_id, resource, limits, use_stored_limits=False)

Check available capacity without consuming.

time_until_available

time_until_available(entity_id, resource, limits, needed, use_stored_limits=False)

Calculate seconds until requested capacity is available.

set_limits

set_limits(entity_id, limits, resource=DEFAULT_RESOURCE)

Store limit configs for an entity.

get_limits

get_limits(entity_id, resource=DEFAULT_RESOURCE)

Get stored limit configs for an entity.

delete_limits

delete_limits(entity_id, resource=DEFAULT_RESOURCE)

Delete stored limit configs for an entity.

get_resource_capacity

get_resource_capacity(resource, limit_name, parents_only=False)

Get aggregated capacity for a resource across all entities.

create_stack

create_stack(stack_options=None)

Create CloudFormation stack for infrastructure.

delete_stack

delete_stack()

Delete the CloudFormation stack and all associated resources.

Synchronous wrapper for :meth:RateLimiter.delete_stack. See the async version for full documentation.

Raises:

Type	Description
StackCreationError	If deletion fails

Example

Cleanup after testing::

limiter = SyncRateLimiter(
    name="test-limits",
    region="us-east-1",
    stack_options=StackOptions(),
)

with limiter:
    # Run tests...
    pass

# Clean up infrastructure
limiter.delete_stack()

Warning

This operation is irreversible. All data will be permanently deleted.

FailureMode

FailureMode

Bases: Enum

Behavior when DynamoDB is unavailable.