RangeInt — A Smarter Integer for Python
Ever written code like this?
hp -= 10
if hp < 0:
hp = 0
Or this?
volume += 5
if volume > 100:
volume = 100
We've all done it. It's boilerplate that clutters your logic every time you have a number that needs to stay within bounds. RangeInt fixes that.
if you just wanna skip to the repo GitHub
What is RangeInt?
RangeInt is a numeric type that automatically clamps itself within a [min, max] range. Every arithmetic operation, every assignment, every mutation — all clamped silently. No if statements, no manual checks.
pip install rangeint
The Basics
from rangeint import RangeInt
hp = RangeInt(100, 0, 100)
hp -= 999
print(hp) # 0 — never goes below min
hp += 9999
print(hp) # 100 — never goes above max
It works transparently as a number too:
print(int(hp)) # 100
print(float(hp)) # 100.0
print(hp == 100) # True
print(hp > 50) # True
Real World Examples
Game dev — player stats
hp = RangeInt(100, 0, 100)
stamina = RangeInt(100, 0, 100)
ammo = RangeInt(30, 0, 30)
hp -= 45 # 55
stamina -= 200 # 0 — clamped, not negative
ammo -= 999 # 0 — clamped, not negative
UI — volume slider
volume = RangeInt(50, 0, 100)
volume += 80 # 100 — won't blast past max
volume -= 200 # 0 — won't go negative
Animation — progress tracking
progress = RangeInt(0, 0, 100)
progress += 10 # 10
progress += 10 # 20
Lerp and Relative Positioning
RangeInt has first-class support for working with values as relative positions — useful for animations, sliders, and interpolation.
relative() — where am I in the range?
hp = RangeInt(75, 0, 100)
hp.relative() # 0.75 — I'm 75% of the way through
lerp_to() — jump to a position
progress = RangeInt(0, 0, 200)
progress.lerp_to(0.5) # 100.0 — jump to midpoint
progress.lerp_to(1.0) # 200.0 — jump to max
nudge_percentage() — shift by a fraction
volume = RangeInt(50, 0, 100)
volume.nudge_percentage(0.1) # +10% of range → 60
volume.nudge_percentage(-0.2) # -20% of range → 40
Threshold Callbacks
This is where RangeInt gets interesting. You can register functions that fire automatically when the value crosses a threshold.
hp = RangeInt(100, 0, 100)
hp.on_percentage(0.25, lambda: print("Critical health!"), directional="down", through=True)
hp.on_percentage(0.0, lambda: print("You died!"), directional="down", through=False)
hp -= 80 # prints "Critical health!"
hp -= 20 # prints "You died!"
The directional parameter controls when the callback fires:
-
"down"— only fires when crossing downward -
"up"— only fires when crossing upward -
"both"— fires in either direction
The through parameter fires the callback if you land exactly on the threshold. if it's True it will activate if it goes through the number e.g if percentage is 0.30 and it goes 0.40 to 0.25 it will activate if it's False it will activate only on the number
Utility Methods
edge_check() — are you at the boundary?
hp = RangeInt(0, 0, 100)
hp.edge_check("min") # True
hp.edge_check("max") # False
is_between() — relative range check
hp = RangeInt(50, 0, 100)
hp.is_between(0.25, 0.75) # True — in the middle half
hp.is_between(0.75, 1.0) # False
set_range() — update bounds on the fly
hp = RangeInt(80, 0, 100)
hp.set_range(0, 50) # value re-clamped to 50
All Operators Work
RangeInt supports every arithmetic and comparison operator you'd expect:
hp = RangeInt(50, 0, 100)
hp + 30 # RangeInt(80)
hp - 999 # RangeInt(0) — clamped
hp * 2 # RangeInt(100) — clamped
hp / 2 # RangeInt(25)
hp += 10
hp -= 5
hp *= 2
hp /= 2
10 + hp # works
3 * hp # works
-hp # works
abs(hp) # works
Install
pip install rangeint
from rangeint import RangeInt
hp = RangeInt(100, 0, 100)
Source code and issues on GitHub. PRs and feedback welcome — especially if you find a use case I haven't thought of!
Built this because I kept writing the same clamping boilerplate in every project. Hope it saves you the same headache.
Top comments (0)