{"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":"python","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,"search_vec":"'0.1.0':71 '2026':75 'activ':77 'balanc':82 'basic':22 'check':62 'classic':30 'collect':10 'control':59 'current':68 'develop':78 'distribut':18 'health':61 'includ':21 'indic':76 'januari':74 'librari':6 'like':60 'load':81 'load-balanc':80 'lvs':32 'lvs-style':31 'need':19 'nginx':41 'nginx-styl':40 'plain':24 'provid':7 'releas':72 'robin':2,14,27,37,47,56,86 'round':1,13,26,36,46,55,85 'round-robin':12,25,35,45,54,84 'roundrobin':5 'runtim':58 'schedul':83 'selector':15 'slow':65 'slow-start':64 'small':9 'smooth':38,43,49,52,88 'start':66 'state':50 'style':33,42 'util':3,79 'various':17 'version':69 'weight':28,34,44,53,87","created_at":"2026-04-12T14:05:58.133322+00:00","updated_at":"2026-04-16T21:08:53.704991+00:00","problems":[{"fix":"Install the library using `pip install roundrobin` once it becomes officially available, or install a pre-release version from source if provided.","cause":"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.","error":"ModuleNotFoundError: No module named 'roundrobin'"},{"fix":"Import the desired selector function by its specific name, for example: `from roundrobin import basic` or `from roundrobin import weighted`.","cause":"The library provides specific selector functions (like `basic`, `weighted`, `smooth`, `smooth_stateful`) directly from the top-level package, rather than a generic 'RoundRobin' class.","error":"ImportError: cannot import name 'RoundRobin' from 'roundrobin'"},{"fix":"Assign 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)`.","cause":"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.","error":"TypeError: 'generator' object is not callable"},{"fix":"Ensure the `weights` list has the same length as the `items` list. For example: `selector = roundrobin.weighted(['a', 'b'], [1, 2])`.","cause":"When using `roundrobin.weighted()` or `roundrobin.smooth()` selectors, the list of `weights` must have the exact same number of elements as the `items` list.","error":"ValueError: Length of items (2) does not match length of weights (3)"},{"fix":"Provide a list or other iterable containing the items: `selector = roundrobin.basic(['item1', 'item2'])`.","cause":"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.","error":"TypeError: 'int' object is not iterable"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/linnik/roundrobin","docs":null,"changelog":null,"pypi":"https://pypi.org/project/roundrobin/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}