throttle-controller
Motivation
This package provides a simple throttle controller for general use-cases. For example, you can use this package to throttle API requests to avoid rate-limiting.
Usage
from throttle_controller import SimpleThrottleController
throttle = SimpleThrottleController.create(default_cooldown_time=3.0)
throttle.wait_if_needed("http://example.com/path/to/api")
throttle.record_use_time_as_now("http://example.com/path/to/api")
... # requests
throttle.wait_if_needed("http://example.com/path/to/api") # wait 3.0 seconds
throttle.record_use_time_as_now("http://example.com/path/to/api")
with statement
from throttle_controller import SimpleThrottleController
throttle = SimpleThrottleController.create(default_cooldown_time=3.0)
for _ in range(10):
with throttle.use("http://example.com/path/to/api"):
# wait if cooldown needed
requests.get("http://example.com/path/to/api")
Deterministic clock for tests
Pass now when you need deterministic tests or replayable behavior:
import datetime
from throttle_controller import SimpleThrottleController
fixed_time = datetime.datetime(2026, 1, 2, 3, 4, 5)
throttle = SimpleThrottleController.create(
default_cooldown_time=3.0,
now=lambda: fixed_time,
)
Stability
This package is currently in Alpha (Development Status :: 3 - Alpha).
- Breaking changes may occur between minor versions while in Alpha.
- The package will be considered for Beta promotion when thread-safe and multi-process support is implemented.
- A stable (1.0) release is planned after Beta validation.
Cooldown timing behaviour
The use() context manager and the manual record_use_time_as_now() call record
the start of each use, not the end. This means the cooldown is measured
start-to-start: the next call may proceed once cooldown_time has elapsed
since the start of the previous call.
call 1 start ──────────── call 1 body (2.9 s) ────── call 1 end
│
└── cooldown_time = 3.0 s ──────────────────────────► call 2 may start
(only 0.1 s after call 1 ends)
If you need end-to-start behaviour (next call waits until at least
cooldown_time after the previous call finishes), record the time after your
work completes instead of relying on the context manager:
throttle.wait_if_needed(key)
result = do_work() # your code here
throttle.record_use_time_as_now(key) # record end of work
Caution
Currently this package supports only to use in single thread / single process use-cases.
Reusing the same controller instance from multiple threads raises RuntimeError.
Development
This repository uses lefthook to run the same checks as CI locally, so problems surface before they reach CI.
# Install dependencies
uv sync
# Install the Git hooks (once; requires lefthook on your PATH)
lefthook install
Once installed, the hooks run automatically:
- pre-commit:
uv run poe check - pre-push:
uv run poe checkanduv run poe test
You can also run the checks manually:
uv run poe check
uv run poe test
CI still runs the full matrix (see .github/workflows/); the hooks only bring that
feedback earlier on your machine.
LICENSE
The 3-Clause BSD License. See also LICENSE file.
Metadata
Release files for throttle-controller 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| throttle_controller-0.4.0.tar.gz | 58.3 kB | With provenance | Details for throttle_controller-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| throttle_controller-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for throttle_controller-0.4.0-py3-none-any.whl |
Total release size: 67.8 kB
Release files / throttle_controller-0.4.0.tar.gz
| Download URL | throttle_controller-0.4.0.tar.gz |
|---|---|
| Size | 58.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3a3d32177001248c9b132301cbbffd5a263146ee85c17fd163be43ee5da8164
|
|
BLAKE2b-256 checksum How to use checksums |
bf743af3c4f5f14bc0c113b00f9572400d6f4b0c554c3a390554b0454e404222
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logRelease files / throttle_controller-0.4.0-py3-none-any.whl
| Download URL | throttle_controller-0.4.0-py3-none-any.whl |
|---|---|
| Size | 9.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
77e332627126fdfc3052998ed63289194a680454d581b6a60cdc0f3ab8592ff1
|
|
BLAKE2b-256 checksum How to use checksums |
657c004874ca883d06c776de9ee67740847076a7d318484b770109e9a0d413a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logSecurity for throttle-controller 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for throttle_controller-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.