Constrained Values

A lightweight Python library for creating type-safe, self-validating value objects — transforming primitive data into meaningful, domain-aware objects with rich validation and transformation pipelines.

---

🧭 Philosophy: Beyond Primitive Types

In most codebases, we pass around raw values without context:

• Is temperature = 25 Celsius or Fahrenheit?
• Is spi_mode = 2 valid for this device?
• What does -32768 mean again?

Primitive values lack meaning, constraints, and domain intent.
This is Primitive Obsession — a subtle but pervasive design smell.

Constrained Values replaces primitives with expressive, validated objects that make validity explicit.
Each object carries its status (OK or EXCEPTION) and associated errors.

By default, invalid values can exist safely and report their state — but if you want to enforce strict invariants, you can enable exception mode to raise immediately on invalid input.

📖 Full Documentation →

---

✨ Features

• 🧩 Rich Value Objects – Replace primitives with expressive, validated domain objects.
• 🔗 Composable Pipelines – Chain multiple validation and transformation strategies.
• 🧠 Built-in Validators – Range checks, enums, type coercion, and more.
• ⚙️ Custom Logic – Easily extend with your own domain-specific rules.
• 🚦 Clear Error Handling – Track validation status and descriptive messages.
• 🧯 Strict/Exception Mode (optional) – By default, invalid values are reported non-destructively; enable strict mode to raise exceptions and enforce invariants at creation.
• 🧾 Type-Safety – Each value enforces its canonical type at runtime.

---

🚀 Installation

pip install constrained-values

💡 Quick Example

from constrained_values import RangeValue

class Temperature(RangeValue):
    """Temperature constrained between 0 and 100°C."""
    def __init__(self, value):
        super().__init__(value, low_value=0, high_value=100)

def main() -> None:
    # ✅ Valid temperature
    t = Temperature(42)
    print("Value:", t.value)        # 42
    print("Status:", t.status.name) # OK
    print("Details:", t.details)    # validation successful

    # 🚫 Invalid temperature
    t_invalid = Temperature(120)
    print("Value:", t_invalid.value)   # None
    print("Status:", t_invalid.status) # Status.EXCEPTION
    print("Details:", t_invalid.details)  # Value must be less than or equal to 100, got 120

if __name__ == "__main__":
    main()

🔥 Strict version

If you want the behavior where invalid input throws immediately, use the StrictValue mixin:

class StrictTemperature(RangeValue, StrictValue):
    """Same range constraint but raises if invalid."""
    def __init__(self, value):
        RangeValue.__init__(self, value, low_value=0, high_value=100)

def main() -> None:
    t = StrictTemperature(42)
    print("Value:", t.value) # 42

    try:
        StrictTemperature(120)
    except ValueError as e:
        print(e) # Failed Constraints for value - '120': Value must be less than or equal to 100, got 120

if __name__ == "__main__":
    main()