## 1. Documentation Scope & Source Confidence **Covered:** `ratelimit/token_bucket.py`, which contains the single class `TokenBucket`: the constructor `__init__`, the public methods `try_acquire` and `wait_time`, and the private helper `_refill`. **Target scope:** `function-level-reference`, as specified by the requester (not inferred). **Audience:** an external contributor preparing a patch, comfortable with Python and concurrency basics, with no knowledge of the project's history or the maintainers' testing and backward-compatibility requirements. **Source form:** The input is a precise prose walkthrough of the module, not the source text itself. In this document, *directly observed* means stated in that walkthrough. Behavior the walkthrough does not state is tagged *inferred* or `<NEEDS-INPUT: id>` rather than assumed. **Outside the supplied material:** The README, other modules in the library, and any tests are known only through what the supplied text says about them. In particular, the README's Redis claim is known only from its quoted wording. Nothing about any other module is independently verified here. **Numbering:** The section numbers follow the standard seven-section layout. Setup and local-development notes are outside this document's scope. ## 2. Architecture & Module Overview The module is one file with one class and one private helper. There are no other classes, module-level functions, or sub-modules in the supplied material. | Component | Responsibility | |---|---| | `TokenBucket` | In-memory token bucket: holds capacity, refill rate, an injectable clock, the current token count, the last-refill time, and a `threading.Lock`. *(Directly observed)* | | `__init__` | Stores configuration and starts the bucket full. | | `try_acquire` | Non-blocking attempt to consume tokens. Returns `bool`. | | `wait_time` | Reports how many seconds remain until a requested number of tokens is available. Returns `float`. | | `_refill` | Private. Adds tokens based on elapsed clock time. Takes no lock itself. | **Locking structure.** Every public method acquires the instance's `threading.Lock`. `_refill` is called only from public methods that already hold it. The lock boundary is therefore the public API, and `_refill` relies on its callers for safety. *(Directly observed)* **Reconciliation with existing documentation:** - **Module docstring ("Simple token bucket.")** is consistent with the code but carries no contract detail. Everything in Section 3 is derived from the code, not from this docstring. - **Comment above `try_acquire` ("thread-safe")** is consistent with the locking structure above, with caveats on scope in Section 6. - **README ("supports Redis-based distributed rate limiting")** does not match the supplied module. No Redis calls exist in `ratelimit/token_bucket.py`, and all state lives in instance memory. This is a divergence, not a detail to paraphrase. See Section 6 and `<NEEDS-INPUT: redis-support-status>`. ## 3. Component & Function Reference **`TokenBucket`** — *(directly observed)*: An in-process, single-instance rate limiter. Each instance tracks its own token count, so two instances (or two processes) never share state. **`__init__(self, capacity: int, refill_rate: float, clock=time.monotonic)`** - **Purpose** *(directly observed)*: Stores `capacity`, `refill_rate` (tokens per second), and the `clock` callable, and sets the initial token count equal to `capacity`, so a new bucket starts full. - **Inputs/outputs:** Takes `capacity`, `refill_rate` and `clock`; returns nothing. - **Side effects:** Creates instance state, including the lock. The initial last-refill time and whether `clock` is called during construction are not stated: `<NEEDS-INPUT: refill-timestamp-handling>`. - **Non-obvious behavior:** - Validation of `capacity` and `refill_rate` (zero, negative, wrong type) is not described. The `int`/`float` annotations are hints only unless enforcement exists elsewhere: `<NEEDS-INPUT: constructor-validation>`. - `clock` is injectable, so time can be controlled from outside. The code gives no stated reason for this. It is directly usable for deterministic testing, but that is an observation, not documented intent. - `clock` must behave like a monotonic non-decreasing time source in seconds. Handling of a clock that moves backward is not described: `<NEEDS-INPUT: clock-regression-handling>`. **`try_acquire(self, tokens: int = 1) -> bool`** - **Purpose** *(directly observed)*: Atomically (under the lock) refills the bucket, then attempts to consume `tokens`. Returns `True` and deducts them if enough are available. Otherwise returns `False` without deducting anything. - **Inputs/outputs:** `tokens` defaults to 1. Returns `bool`. Raises `ValueError` if `tokens` is greater than `capacity`. The walkthrough states the error is raised "directly." - **Side effects:** - Calls `_refill()` first on every call. *(Directly observed)* - Deducts tokens on success. *(Directly observed)* - A `False` result does not deduct tokens, but it is not state-free: because `_refill()` runs first, the stored token count and, presumably, the last-refill timestamp advance even on failure. *(Inferred; the walkthrough does not say whether `_refill` updates the timestamp: `<NEEDS-INPUT: refill-timestamp-handling>`.)* - **Non-obvious behavior:** - Whether the `ValueError` check occurs before or after `_refill()` is not specified: `<NEEDS-INPUT: try-acquire-validation-order>`. - Requests of 0 or negative `tokens` are not described as validated: `<NEEDS-INPUT: nonpositive-token-requests>`. - A request larger than `capacity` is rejected with an exception, not `False`. Callers cannot treat "not enough tokens" and "can never be satisfied" identically. **`wait_time(self, tokens: int = 1) -> float`** - **Purpose** *(directly observed)*: Returns the seconds still to wait until `tokens` are available, or `0.0` if enough tokens are already present. Presumably this is the token deficit divided by `refill_rate`. *(Inferred; the formula is not stated.)* - **Inputs/outputs:** `tokens` defaults to 1. Returns `float`. - **Side effects:** Holds the lock for its duration. *(Directly observed)* Whether it calls `_refill()`, and therefore mutates the token count and timestamp despite its query-like name, is not stated: `<NEEDS-INPUT: wait-time-refill-behavior>`. - **Non-obvious behavior:** - The result is a snapshot. The lock is released when the method returns, so a subsequent `try_acquire` is a separate critical section. Another thread may consume tokens in between, or time may have advanced. *(Inferred from the per-method locking.)* - Behavior for `tokens` greater than `capacity` (raise `ValueError` as `try_acquire` does, or return a wait that can never be satisfied) is not stated: `<NEEDS-INPUT: wait-time-oversized-request>`. **`_refill(self)`** - **Purpose** *(directly observed)*: Adds `refill_rate × (current clock reading − last refill time)` to the token count, capped at `capacity`. - **Inputs/outputs:** No arguments; no return value described. - **Side effects:** Reads the injected `clock` and mutates the token count. It presumably also updates the last-refill time. *(Inferred; see `<NEEDS-INPUT: refill-timestamp-handling>`.)* - **Non-obvious behavior:** - **Takes no lock.** Safety depends entirely on callers holding the instance lock. *(Directly observed)* Any new code path that calls `_refill` must do so under the lock. - Only an upper cap is described. No lower bound on elapsed time is stated: `<NEEDS-INPUT: clock-regression-handling>`. - Refill is computed lazily on demand. No background thread or timer is described. ## 4. Data Flow & Key Interactions **Primary flow: `try_acquire`** *(directly observed unless tagged)* 1. A caller thread invokes `try_acquire(tokens)`. This is the only trigger. No scheduled or background activity is described. 2. The method holds the instance `threading.Lock` for the duration of its work. 3. `_refill()` reads the injected `clock`, computes elapsed time since the last refill, adds `refill_rate × elapsed` to the token count, and caps it at `capacity`. 4. If `tokens` is greater than `capacity`, `ValueError` is raised. The position of this check relative to step 3 is undetermined: `<NEEDS-INPUT: try-acquire-validation-order>`. 5. If the token count is at least `tokens`, the count is reduced and `True` is returned. Otherwise `False` is returned with no deduction. **Secondary flow: `wait_time`** 1. A caller invokes `wait_time(tokens)`, which holds the lock. 2. It computes and returns the remaining wait in seconds, or `0.0` if sufficient tokens exist. Whether step 3 of the flow above (`_refill()`) also runs first is undetermined: `<NEEDS-INPUT: wait-time-refill-behavior>`. **Interaction between the two public methods.** The methods share state only through the instance's token count and timestamp. A caller that uses `wait_time` to decide how long to sleep before calling `try_acquire` performs two independent critical sections. Another thread's `try_acquire` can run between them, so the second call can still return `False`. *(Inferred.)* **Persistence and external I/O.** None appears in the supplied module. All state is in instance memory, and no network, file, or Redis calls are described. ## 6. Known Limitations & Divergences **Divergence: README vs. code.** The README claims "supports Redis-based distributed rate limiting." The supplied module contains no Redis calls and keeps all state in per-instance memory, so two processes or hosts using `TokenBucket` do not share limits. Whether Redis support lives in another module, was removed, or is planned is not determinable from the supplied material. Contributors should not assume any distributed behavior from this class: `<NEEDS-INPUT: redis-support-status>`. **Divergence: "thread-safe" is narrower than it sounds.** The comment is supported by the per-method locking, with these limits: - Safety is per instance and across threads in one process only. - The lock is a non-reentrant `threading.Lock`. A subclass or new public method that calls another public method while holding the lock would deadlock. A custom `clock` that calls back into the same bucket would also deadlock. *(Inferred from the lock type.)* Whether subclassing is supported is unknown: `<NEEDS-INPUT: subclassing-support>`. - `wait_time` followed by `try_acquire` is not atomic (see Section 4). - `_refill` is unlocked by design. It is safe only because current callers hold the lock. **Divergence: "returns False without changing state."** In `try_acquire`, this holds for the deduction only. `_refill()` runs first and can advance the token count (and presumably the timestamp) even when the result is `False`. **Naming vs. behavior: `wait_time`.** The name suggests a read-only query. Whether it refills, and thus mutates state, is not confirmed: `<NEEDS-INPUT: wait-time-refill-behavior>`. **Inconsistent handling of oversized requests.** `try_acquire` raises `ValueError` for `tokens` greater than `capacity`. `wait_time`'s behavior for the same input is not documented: `<NEEDS-INPUT: wait-time-oversized-request>`. **Fragile or unvalidated areas** (none are described as guarded): - Constructor arguments such as a `refill_rate` of 0 or a non-positive `capacity`. Depending on how `wait_time` computes its result, a zero rate may produce an unbounded or erroring wait: `<NEEDS-INPUT: constructor-validation>`. - Zero or negative `tokens` in `try_acquire` and `wait_time`: `<NEEDS-INPUT: nonpositive-token-requests>`. - Clocks that move backward or return non-seconds values: `<NEEDS-INPUT: clock-regression-handling>`. **TODO/FIXME comments.** None appear in the supplied description. Because the source text itself was not supplied, their absence in the file is unconfirmed: `<NEEDS-INPUT: todo-fixme-presence>`. **Documentation gap.** The module docstring ("Simple token bucket.") states no contract, so the observed behavior above is the de facto public interface. ## 7. Open Questions & Data Requests 1. `<NEEDS-INPUT: redis-support-status>`: Does Redis-based distributed rate limiting exist anywhere in the library? If it is in another module, which one? If it is planned or was removed, should the README be corrected? 2. `<NEEDS-INPUT: wait-time-refill-behavior>`: Does `wait_time` call `_refill()`, and is it intended to mutate state? 3. `<NEEDS-INPUT: wait-time-oversized-request>`: What should `wait_time` do when `tokens` exceeds `capacity`: raise `ValueError` like `try_acquire`, or return a value? Is the current behavior intentional? 4. `<NEEDS-INPUT: try-acquire-validation-order>`: Is the `ValueError` check performed before or after `_refill()`, and before or after the lock is acquired? 5. `<NEEDS-INPUT: refill-timestamp-handling>`: How is the last-refill time initialized in `__init__`, and does `_refill` update it on every call, including when no tokens are added? 6. `<NEEDS-INPUT: constructor-validation>`: Are `capacity` and `refill_rate` validated anywhere (for example for zero or negative values)? Is a `refill_rate` of 0 a supported configuration? 7. `<NEEDS-INPUT: nonpositive-token-requests>`: What is the intended behavior for `tokens` of 0 or less in `try_acquire` and `wait_time`? 8. `<NEEDS-INPUT: clock-regression-handling>`: What is the expected behavior if the injected `clock` returns a value earlier than the last refill time? 9. `<NEEDS-INPUT: subclassing-support>`: Is subclassing `TokenBucket`, or calling its public methods from within a held lock, supported or discouraged? 10. `<NEEDS-INPUT: todo-fixme-presence>`: Does the source file contain TODO/FIXME comments that were not included in the supplied description? 11. `<NEEDS-INPUT: testing-and-compat-requirements>`: What testing expectations apply to patches (framework, required tests, concurrency or fake-clock test patterns)? What is the backward-compatibility policy: which names and signatures are public, and how are changes to `__init__`, `try_acquire`, `wait_time`, return types, or the `ValueError` behavior handled? None of this is determinable from the supplied material.