I built a python library to make ranged integers

kp-dev1 — Mon, 06 Apr 2026 08:59:48 +0000

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.

DEV Community: kp-dev1