Rounders

Common errors

• TypeError: round() got an unexpected keyword argument 'mode'

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

• AttributeError: module 'rounders' has no attribute 'signif'

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

• 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.

  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.
  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`.

Warnings

• gotcha 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.
  Fix: Be explicit with imports: `import builtins; from rounders import round as rounders_round` or always specify `mode` when using `rounders.round`.
• gotcha 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.
  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.
• gotcha 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).
  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`).

Install

• pip install rounders Install with pip

Imports

• round
  wrong:

  import rounders; rounders.round()

  correct:

  from rounders import round

  While `rounders.round` works, direct import shadows the built-in `round` function, allowing for seamless integration of custom rounding modes.
• round_to_figures

  from rounders import round_to_figures

• TIES_TO_AWAY
  wrong:

  import rounders; rounders.TIES_TO_AWAY

  correct:

  from rounders import TIES_TO_AWAY

  Rounding modes are typically imported directly for cleaner code.

Quickstart

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`.

from rounders import round, TIES_TO_AWAY, TO_MINUS, round_to_figures

# Using a different rounding mode (TIES_TO_AWAY - commonly taught in schools)
result_away = round(2.5, mode=TIES_TO_AWAY)
print(f"round(2.5, mode=TIES_TO_AWAY): {result_away}")

# Rounding towards negative infinity (like math.floor)
result_tominus = round(2.97, 1, mode=TO_MINUS)
print(f"round(2.97, 1, mode=TO_MINUS): {result_tominus}")

# Rounding to significant figures
result_figures = round_to_figures(12345.67, 3)
print(f"round_to_figures(12345.67, 3): {result_figures}")

# Using default mode (TIES_TO_EVEN / Banker's Rounding)
result_default = round(2.5)
print(f"round(2.5) [default TIES_TO_EVEN]: {result_default}")