Add capacity method

[ashrub-holvi]

Hi, thank you for project!

What about adding:

    def capacity(self) -> int:
        """Return capacity remaining in the limiter
        """
        self._leak()
        return self._level

?
I am still thinking, but feels like it can be needed in case you want to know how many new requests you can pick up, for example from database.

[wuxmax]

This is not the capacity. This is just the level of the bucket. To get the capacity would do this:

    def capacity(self) -> int:
        """Return capacity remaining in the limiter
        """
        self._leak()
        return self.max_rate - self._level

At least that is how I understand it.

[ashrub-holvi]

Thank you, I think you are right, likely I mixed it with token bucket.

[mjpieters]

The value is a moving target, every tick of the clock lowers the level in the bucket, freeing up more capacity, so if you are using this value in a follow-up calculation the result could be wrong based on how much time the additional work took.

This makes me wary of adding such an accessor (which should probably be called available_capacity, and could just be a property).

What's the specific use case for this?

[wuxmax]

I see your point and agree with the naming and the property status. I just use this for logging, because i want to monitor the capacity usage.

[mjpieters]

I see your point and agree with the naming and the property status. I just use this for logging, because i want to monitor the capacity usage.

In that case, would logging the repr() of the limiter be helpful?

That gives you the level, as well as the number of tasks waiting and how soon the next waiting task is due to pass.

[parmsib]

Chiming in with a related use-case.
I want to track the remaining capacity as a prometheus metric exposed by my service using aiolimiter.

Parsing out the result of a repr into separate metric values is not preferable to an API with dedicated properties or functions for getting them separately.

The fact that any value returned would be "out of date" is not an issue here, as prometheus by design scrapes (i.e samples) targets at regular intervals, and resulting values are inherently assumed to only be representative of the time-of-scrape.