# zhuozhuocrayon/throttled-py architecture

> Architecture diagram of the GitHub repository zhuozhuocrayon/throttled-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhuozhuocrayon/throttled-py
- Repository: https://github.com/zhuozhuocrayon/throttled-py

## Overview

The “throttled-py” project is a high-performance Python rate-limiting library that supports a variety of limit algorithms (fixed window, sliding window, token bucket, leaking bucket & GCRA) as well as multiple storage backends (in-memory and Redis). In essence, this is not a full-stack application but rather a specialized library that provides both a generic API for rate limiting and implementations of different algorithms and stores.

##### Main Components
- API Interface: At the top level, you have a central API (the Throttled class) that exposes methods like limit() and peek(). This is the entry point for users, whether they call the functions directly or use the class as a decorator.
- Rate Limiter Algorithms: Under the “throttled” package, the “rate_limter” directory contains modules for each supported algorithm (fixed_window, sliding_window, token_bucket, leaking_bucket, gcra). Notice that some algorithms also have Lua scripts for Redis implementations.
- Storage Backends: The “throttled/store” directory provides abstraction for the actual state storage. Here you have implementations for MemoryStore (in-memory, thread-safe with LRU behavior) and RedisStore (which wraps the redis-py client and exposes configuration for a distributed store).
- Exceptions & Utilities: Modules like “exceptions.py” and “utils.py” provide supporting behaviors such as error handling (e.g., LimitedError) and additional benchmarking or helper functions.
- Configuration & Deployment: Outside of the core package, you have configuration files (Dockerfile, Makefile, GitHub workflows, etc.) to support continuous integration, code quality, and deployment processes.

##### Relationships and Data Flow
- Next, the request is handed off to the Throttled class. This class encapsulates the chosen rate-limiting algorithm (determined by the “using” parameter) and the quota policy.
- The Throttled class then delegates to the appropriate algorithm implementation found in the “throttled/rate_limter” modules. Within these modules, the algorithm computes the new state (for example, remaining tokens or time until reset) based on the incoming “cost” or request.
- At the same time, the chosen storage backend from “throttled/store” is used to fetch and update the state associated with a given key. The design abstracts the storage access so that the same API can work with either in-memory or Redis-based storage.
- Error handling is performed via exceptions (e.g., when a LimitedError is thrown when a limit is exceeded).

##### Architectural Patterns and Design Principles
- Modularity and Abstraction: The library cleanly separates rate-limiting logic from storage access, making it easier to plug different storage backends.
- Extensibility: With separate directories for tests, examples, and documentation, the project is set up for maintainability and testing across multiple components.

##### Technology and Frameworks
- Python (>=3.8) is the primary language.
- Redis (via redis-py) is used for distributed storage.
- The project uses Python decorators to enable syntax like “@Throttled(…)” for rate-limited functions.
- Lua scripts (in “throttled/rate_limter/lua”) indicate that for some algorithms, particularly in a Redis context, the logic is offloaded to Redis scripting for performance.

##### Detail Orientation
- Be very detailed: include the separation between the API (Throttled class), algorithm selection (with specific modules like fixed_window.py, token_bucket.py, etc.), and storage backends (MemoryStore and RedisStore) as the essential architectural elements.
- Do not be afraid to split the project into as many components as possible – detailing even the Lua script components can illustrate that Redis-specific algorithms offload some computations directly to Redis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Code
    Client["Client Code / User Code"]:::clientStyle

    %% API Layer
    subgraph "API Layer"
        Throttled["Throttled Class"]:::api
    end

    %% Rate Limiter Strategy
    subgraph "Rate Limiter Strategy"
        AlgSelector["Algorithm Selector"]:::selector
        Fixed["Fixed Window"]:::alg
        Sliding["Sliding Window"]:::alg
        Token["Token Bucket"]:::alg
        Leaking["Leaking Bucket"]:::alg
        GCRA["GCRA"]:::alg
        Lua["Lua Scripts"]:::alg
    end

    %% Storage Backends
    subgraph "Storage Backends"
        Memory["MemoryStore (In-Memory)"]:::storage
        Redis["RedisStore"]:::storage
    end

    %% Supporting Components
    Exceptions["Exceptions"]:::support
    Utilities["Utilities"]:::support

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        Docker["Dockerfile"]:::config
        Makefile["Makefile"]:::config
        Workflows["GitHub Workflows"]:::config
    end

    %% Connections
    Client -->|"calls"| Throttled
    Throttled -->|"delegates_to"| AlgSelector

    AlgSelector -->|"employs"| Fixed
    AlgSelector -->|"employs"| Sliding
    AlgSelector -->|"employs"| Token
    AlgSelector -->|"employs"| Leaking
    AlgSelector -->|"employs"| GCRA
    AlgSelector -->|"employs"| Lua

    Fixed -->|"state_read/write"| Memory
    Fixed -->|"state_read/write"| Redis
    Sliding -->|"state_read/write"| Memory
    Sliding -->|"state_read/write"| Redis
    Token -->|"state_read/write"| Memory
    Token -->|"state_read/write"| Redis
    Leaking -->|"state_read/write"| Memory
    Leaking -->|"state_read/write"| Redis
    GCRA -->|"state_read/write"| Memory
    GCRA -->|"state_read/write"| Redis

    Lua -->|"supports"| Fixed
    Lua -->|"supports"| Sliding
    Lua -->|"supports"| Token
    Lua -->|"supports"| Leaking
    Lua -->|"supports"| GCRA

    Throttled -->|"handles_error"| Exceptions
    Throttled -->|"utilizes"| Utilities

    %% Click Events
    click Throttled "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/throttled.py"
    click Fixed "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/rate_limter/fixed_window.py"
    click Sliding "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/rate_limter/sliding_window.py"
    click Token "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/rate_limter/token_bucket.py"
    click Leaking "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/rate_limter/leaking_bucket.py"
    click GCRA "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/rate_limter/gcra.py"
    click Lua "https://github.com/zhuozhuocrayon/throttled-py/tree/main/throttled/rate_limter/lua"
    click Memory "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/store/memory.py"
    click Redis "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/store/redis.py"
    click Exceptions "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/exceptions.py"
    click Utilities "https://github.com/zhuozhuocrayon/throttled-py/blob/main/throttled/utils.py"
    click Docker "https://github.com/zhuozhuocrayon/throttled-py/tree/main/Dockerfile"
    click Makefile "https://github.com/zhuozhuocrayon/throttled-py/tree/main/Makefile"
    click Workflows "https://github.com/zhuozhuocrayon/throttled-py/tree/main/.github/workflows/"

    %% Styles
    classDef clientStyle fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef api fill:#85C1E9,stroke:#2874A6,stroke-width:2px;
    classDef selector fill:#A9DFBF,stroke:#52BE80,stroke-width:2px;
    classDef alg fill:#82E0AA,stroke:#27AE60,stroke-width:2px;
    classDef storage fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef support fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef config fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
