Decorator observability support

[hhuang1231]

When I use the throttled-py decorator to limit the flow, it seems that it can not find the ability to obtain RateLimitResult to observe the flow limit operation.

I am not sure if there are other better solutions, but the observation ability I want may be similar to tenacity.

If there is hope, I will support it as soon as possible. I look forward to your reply.

[s3ich4n]

I took another look at this issue, and I think the smallest workable option is a ContextVar for decorator usage only.

I also tried a small local PoC, and the basic sync/async behavior, nested restore, and hook timing all seemed to work as expected.

The contract I have in mind is intentionally narrow:

• expose only the current decorated invocation's result
• the value reflects the final RateLimitResult returned by self.limit(), which includes the full hook chain if hooks are configured
• hooks themselves run before the ContextVar is set, so they should use call_next() return value or HookContext to observe the result
• nested decorators restore the outer value on exit (standard LIFO semantics)
• no request-level aggregation across multiple throttled calls

For example, the intended usage would be something like:

from throttled import Throttled, current_rate_limit_result


@Throttled(key="/api", quota="10/m")
def handler() -> dict[str, float | int]:
    result = current_rate_limit_result.get()
    return {
        "remaining": result.state.remaining,
        "reset_after": result.state.reset_after,
    }

The async path would work the same way:

from throttled.asyncio import Throttled, current_rate_limit_result


@Throttled(key="/api", quota="10/m")
async def handler() -> dict[str, float | int]:
    result = current_rate_limit_result.get()
    return {
        "remaining": result.state.remaining,
        "reset_after": result.state.reset_after,
    }

For the limited path, I would keep the current behavior unchanged:

try:
    handler()
except LimitedError as exc:
    rejected = exc.rate_limit_result

The ContextVar would only be set for the successful decorator path right before entering the function body, then reset on exit.
Inside the decorated body, the value is guaranteed to be non-None.

One open question is the public API shape: should this export the raw ContextVar (as shown above), or a getter function like get_current_rate_limit_result()?

If we expose the raw ContextVar, my current assumption is:

• from throttled import current_rate_limit_result
• from throttled.asyncio import current_rate_limit_result

with both import paths referring to the same underlying object.

The raw ContextVar is more flexible for testing, but a getter hides the underlying mechanism. I am leaning toward the raw ContextVar, but happy to go either way.

Does this direction sound reasonable? If so, I can open a small draft PR.

[ZhuoZhuoCrayon]

@s3ich4n Thanks for taking another look at this, and also for the thoughtful ContextVar proposal.

My current read is that the original user need here is mainly about observability around decorator-based rate limiting. For that specific goal, the existing hook mechanism already seems to cover the core use case well through call_next() and HookContext, without introducing another public API surface right away.

Because of that, I am currently leaning toward treating this issue as something that can likely be addressed through hooks and clearer documentation/examples, rather than adding ContextVar support immediately.

If we later confirm that there is a separate concrete need to access the current RateLimitResult from inside the decorated function body itself, then the narrower ContextVar direction would still be reasonable to revisit as a follow-up.