Install & Compatibility
Where this runs
tested against v0.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
roundrobin
✓ import roundrobin
The library is imported directly as 'roundrobin', and its functions (e.g., `basic`, `weighted`, `smooth`, `smooth_stateful`) are accessed as attributes.
This quickstart demonstrates the `basic()`, `weighted()`, `smooth()`, and `smooth_stateful()` functions. It shows how to initialize each type of round-robin selector and retrieve items. For `smooth_stateful()`, an example of dynamically adjusting an item's weight at runtime is also included.
import roundrobin
# Basic round-robin
get_basic = roundrobin.basic(["A", "B", "C"])
print(''.join([get_basic() for _ in range(7)]))
# Weighted round-robin
get_weighted = roundrobin.weighted([("A", 5), ("B", 1), ("C", 1)])
print(''.join([get_weighted() for _ in range(7)]))
# Smooth weighted round-robin
get_smooth = roundrobin.smooth([("A", 5), ("B", 1), ("C", 1)])
print(''.join([get_smooth() for _ in range(7)]))
# Stateful smooth weighted round-robin with runtime controls
rr_stateful = roundrobin.smooth_stateful([("A", 5), ("B", 1), ("C", 1)])
outputs = []
for _ in range(14):
outputs.append(rr_stateful())
print(''.join(outputs))
# Example of runtime weight adjustment with smooth_stateful
rr_stateful_adjust = roundrobin.smooth_stateful([("A", 5), ("B", 1), ("C", 1)])
rr_stateful_adjust.set("A", weight=2)
outputs_adjust = []
for _ in range(14):
outputs_adjust.append(rr_stateful_adjust())
print(''.join(outputs_adjust))
Debug
Known issues
breakingAs of version 0.1.0, initializing round-robin selectors (`basic`, `weighted`, `smooth`, `smooth_stateful`) with an empty dataset will now raise a `ValueError` instead of potentially returning an empty sequence or causing other unexpected behavior.fixEnsure that the iterable provided to any `roundrobin` selector function is not empty. Implement a check for non-empty input before creating a selector instance.
affects: 0.1.0 and later
breakingVersion 0.1.0 introduced a breaking change that disallows negative weights in `weighted()`, `smooth()`, and `smooth_stateful()` functions. Providing a negative weight will now raise a `ValueError`.fixAll weights provided to `weighted()`, `smooth()`, or `smooth_stateful()` must be non-negative (zero or positive). Adjust your weighting logic to ensure only valid weights are passed.
affects: 0.1.0 and later
gotchaThe `smooth_stateful()` selector maintains an internal state for each item. When you use methods like `set()` or `disable()` to adjust weights or status, these changes affect future picks but do not 'restart' the scheduling sequence from scratch. If a completely fresh distribution is desired after changes, a new `smooth_stateful` instance should be created.fixBe aware of the stateful nature of `smooth_stateful`. If you need to ensure a predictable starting sequence after configuration changes, instantiate a new `roundrobin.smooth_stateful` object.
affects: All versions with `smooth_stateful` (0.1.0 and later)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'roundrobin'
The 'roundrobin' library version 0.1.0 is slated for release in January 2026 and is not yet available on PyPI or installed in your current Python environment.
fixInstall the library using `pip install roundrobin` once it becomes officially available, or install a pre-release version from source if provided.
ImportError: cannot import name 'RoundRobin' from 'roundrobin'
The library provides specific selector functions (like `basic`, `weighted`, `smooth`, `smooth_stateful`) directly from the top-level package, rather than a generic 'RoundRobin' class.
fixImport the desired selector function by its specific name, for example: `from roundrobin import basic` or `from roundrobin import weighted`.
TypeError: 'generator' object is not callable
The `roundrobin.basic()` (or other selector) function returns an iterator or generator object, which needs to be advanced using `next()` or iterated over, not called directly like a function to get the next item.
fixAssign the result of the selector function to a variable and then call `next()` on that variable to get the next item: `selector = roundrobin.basic(['a', 'b']); item = next(selector)`.
ValueError: Length of items (2) does not match length of weights (3)
When using `roundrobin.weighted()` or `roundrobin.smooth()` selectors, the list of `weights` must have the exact same number of elements as the `items` list.
fixEnsure the `weights` list has the same length as the `items` list. For example: `selector = roundrobin.weighted(['a', 'b'], [1, 2])`.
TypeError: 'int' object is not iterable
All `roundrobin` selector functions expect their first argument to be an iterable (like a list, tuple, or set) of the items to be distributed, not a single non-iterable value.
fixProvide a list or other iterable containing the items: `selector = roundrobin.basic(['item1', 'item2'])`.
Upgrade
Version history
0.1.0latest on PyPI · released Jan 25, 2026
Audit
Dependencies
No dependency data recorded yet.