{"id":8606,"library":"rounders","title":"Rounders","description":"The `rounders` package extends Python's built-in `round` function, providing a comprehensive collection of decimal rounding functionalities. It offers drop-in replacements for `round` that support thirteen different rounding modes beyond Python's default Banker's rounding, as well as functionality for rounding to a specified number of significant figures. The current version is 0.2.0, released on June 9, 2024, with an active development status.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/mdickins/rounders","tags":["rounding","decimal","significant figures","mathematics"],"install":[{"cmd":"pip install rounders","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"While `rounders.round` works, direct import shadows the built-in `round` function, allowing for seamless integration of custom rounding modes.","wrong":"import rounders; rounders.round()","symbol":"round","correct":"from rounders import round"},{"symbol":"round_to_figures","correct":"from rounders import round_to_figures"},{"note":"Rounding modes are typically imported directly for cleaner code.","wrong":"import rounders; rounders.TIES_TO_AWAY","symbol":"TIES_TO_AWAY","correct":"from rounders import TIES_TO_AWAY"}],"quickstart":{"code":"from rounders import round, TIES_TO_AWAY, TO_MINUS, round_to_figures\n\n# Using a different rounding mode (TIES_TO_AWAY - commonly taught in schools)\nresult_away = round(2.5, mode=TIES_TO_AWAY)\nprint(f\"round(2.5, mode=TIES_TO_AWAY): {result_away}\")\n\n# Rounding towards negative infinity (like math.floor)\nresult_tominus = round(2.97, 1, mode=TO_MINUS)\nprint(f\"round(2.97, 1, mode=TO_MINUS): {result_tominus}\")\n\n# Rounding to significant figures\nresult_figures = round_to_figures(12345.67, 3)\nprint(f\"round_to_figures(12345.67, 3): {result_figures}\")\n\n# Using default mode (TIES_TO_EVEN / Banker's Rounding)\nresult_default = round(2.5)\nprint(f\"round(2.5) [default TIES_TO_EVEN]: {result_default}\")","lang":"python","description":"This quickstart demonstrates importing `round` with custom modes and `round_to_figures` for significant digit rounding. It highlights the behavior of `TIES_TO_AWAY` versus the default `TIES_TO_EVEN` (Banker's rounding) and `TO_MINUS`."},"warnings":[{"fix":"Be explicit with imports: `import builtins; from rounders import round as rounders_round` or always specify `mode` when using `rounders.round`.","message":"The `rounders.round` function, when imported, shadows Python's built-in `round`. While this is the intended design for applying custom rounding modes, users might accidentally use the `rounders` version when they expect the built-in behavior, or vice-versa, if not careful about import statements.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always explicitly specify the desired rounding mode using the `mode` argument (e.g., `round(2.5, mode=TIES_TO_AWAY)`) if you require a behavior different from Banker's Rounding.","message":"Users often expect `round(X.5)` to always round up (e.g., `2.5` to `3`), which is `TIES_TO_AWAY` behavior. Python's built-in `round()` (and `rounders`' default behavior if no mode is specified) uses `TIES_TO_EVEN` (Banker's Rounding), where halves round to the nearest even integer (e.g., `2.5` to `2`, `3.5` to `4`). This can lead to unexpected results if the desired rounding mode is not explicitly set.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the correct library name and purpose: `rounders` for extended numerical rounding, `rounder` for rounding numbers within complex Python objects. Double-check import statements (`from rounders import ...` vs `import rounder as r`).","message":"The package `rounder` (singular) and `rounders` (plural) are different libraries with distinct functionalities. Users might confuse them, leading to incorrect imports or assumptions about available features (e.g., `rounder` handles rounding in complex objects, while `rounders` provides flexible rounding modes for individual numbers).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `from rounders import round` is correctly executed and that the `round` function being called is indeed from the `rounders` library. You can verify this by printing `round` (e.g., `print(round)` should show it pointing to the `rounders` module).","cause":"You are likely calling Python's built-in `round()` function instead of the `rounders.round` function, which accepts the `mode` argument. This happens if `from rounders import round` was not executed, or if another `round` function is in scope.","error":"TypeError: round() got an unexpected keyword argument 'mode'"},{"fix":"Use `round_to_figures` from the `rounders` library for rounding to significant figures: `from rounders import round_to_figures; round_to_figures(123.45, 3)`. If you need features from the `rounder` library, install and import it separately.","cause":"The `rounders` library uses `round_to_figures` for rounding to significant figures, not a function named `signif`. The `signif` function is found in the unrelated `rounder` (singular) package.","error":"AttributeError: module 'rounders' has no attribute 'signif'"},{"fix":"Import and explicitly use the `TIES_TO_AWAY` rounding mode from `rounders`: `from rounders import round, TIES_TO_AWAY; round(2.5, mode=TIES_TO_AWAY)` will yield `3` and `round(3.5, mode=TIES_TO_AWAY)` will yield `4`.","cause":"This is Python's default Banker's Rounding (`TIES_TO_EVEN`) behavior for floats. It rounds halfway cases to the nearest even integer to avoid statistical bias. Many users expect 'round half up' behavior.","error":"Values like round(2.5) and round(3.5) both round to the nearest even number (2 and 4 respectively), but I expected 3 and 4."}]}