rounders

library0.2.0pypypi✓ verified 87d ago

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.

serialization

pip install rounders

github ↗package ↗

INSTALL

IMPORT

SIG · ROUNDERS

rounders

serializationpythonv0.2.0

Install

1.6s avg

Import

50ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.053s · 18MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.048s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

round

✓ from rounders import round

✗ import rounders; rounders.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

✓ from rounders import TIES_TO_AWAY

✗ import rounders; rounders.TIES_TO_AWAY

Rounding modes are typically imported directly for cleaner code.

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

Debug

Known issues

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

affects: All versions

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

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

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'

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.

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

Upgrade

Version history

0.2.0latest on PyPI · released Jun 9, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/mdickinson/rounders ↗

packagehttps://pypi.org/project/rounders/ ↗