{"id":4749,"library":"roundrobin","title":"Round Robin Utilities","description":"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.","status":"active","version":"0.1.0","language":"en","source_language":"en","source_url":"https://github.com/linnik/roundrobin","tags":["utility","load-balancing","scheduling","round-robin","weighted","smooth"],"install":[{"cmd":"pip install roundrobin","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The library is imported directly as 'roundrobin', and its functions (e.g., `basic`, `weighted`, `smooth`, `smooth_stateful`) are accessed as attributes.","symbol":"roundrobin","correct":"import roundrobin"}],"quickstart":{"code":"import roundrobin\n\n# Basic round-robin\nget_basic = roundrobin.basic([\"A\", \"B\", \"C\"])\nprint(''.join([get_basic() for _ in range(7)]))\n\n# Weighted round-robin\nget_weighted = roundrobin.weighted([(\"A\", 5), (\"B\", 1), (\"C\", 1)])\nprint(''.join([get_weighted() for _ in range(7)]))\n\n# Smooth weighted round-robin\nget_smooth = roundrobin.smooth([(\"A\", 5), (\"B\", 1), (\"C\", 1)])\nprint(''.join([get_smooth() for _ in range(7)]))\n\n# Stateful smooth weighted round-robin with runtime controls\nrr_stateful = roundrobin.smooth_stateful([(\"A\", 5), (\"B\", 1), (\"C\", 1)])\noutputs = []\nfor _ in range(14):\n    outputs.append(rr_stateful())\nprint(''.join(outputs))\n\n# Example of runtime weight adjustment with smooth_stateful\nrr_stateful_adjust = roundrobin.smooth_stateful([(\"A\", 5), (\"B\", 1), (\"C\", 1)])\nrr_stateful_adjust.set(\"A\", weight=2)\noutputs_adjust = []\nfor _ in range(14):\n    outputs_adjust.append(rr_stateful_adjust())\nprint(''.join(outputs_adjust))","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"0.1.0 and later"},{"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.","message":"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`.","severity":"breaking","affected_versions":"0.1.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions with `smooth_stateful` (0.1.0 and later)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}