Round Robin Utilities

0.1.0 · active · verified Sun Apr 12

The `roundrobin` library provides a small collection of round-robin selectors for various distribution needs. It includes `basic()` for plain round-robin, `weighted()` for classic LVS-style weighted round-robin, `smooth()` for Nginx-style smooth weighted round-robin, and `smooth_stateful()` for smooth weighted round-robin with runtime controls like health checks or slow-start. The current version is 0.1.0, released in January 2026, indicating active development.

Warnings

breaking As 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.
Fix: Ensure that the iterable provided to any `roundrobin` selector function is not empty. Implement a check for non-empty input before creating a selector instance.
breaking Version 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`.
Fix: All 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.
gotcha The `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.
Fix: Be 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.

Install

pip install roundrobin Install latest version

Imports

roundrobin
```
import roundrobin
```
The library is imported directly as 'roundrobin', and its functions (e.g., `basic`, `weighted`, `smooth`, `smooth_stateful`) are accessed as attributes.

Quickstart

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))

view raw JSON →