Constraints

Constraint classes for runtime validation of Value instances.

Base Interface

class valguard.constraints.Constraint

Bases: ABC

Represents a constraint that may be imposed on a Value.

__str__()

Return a string representation of the constraint.

Return type:

str

abstractmethod validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

TypedValue[Any]

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

Note

The validate() method performs more than basic type checking — it often returns an instance of the appropriate Value subclass, such as StrValue or IntValue.

Autodoc may not reflect this casting behavior explicitly, so refer to implementation details or examples for precise return types.

Logical Helpers

valguard.constraints.implies(a, b)

Returns True if a implies b.

If constraint a implies constraint b then if a value satisfies constraint a, it is guaranteed to also satisfy constraint b.

A class implies another constraint if every instance of that class implies the constraint. A constraint implies a class if it implies at least one instance of that class. And a class implies a class if each instance of the first class implies at least one instance of the second class.

Return type:

bool

Generic Constraints

class valguard.constraints.AnyConstraint

A constraint that accepts any Value instance without additional checks.

This constraint enforces only that the input is an instance of Value, but imposes no further semantic restrictions.

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

TypedValue[Any]

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

class valguard.constraints.BoolConstraint

Constrains a value to be a boolean.

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

BoolValue

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

class valguard.constraints.IntConstraint

Constrains a value to be an integer.

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

IntValue

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

class valguard.constraints.FloatConstraint

Constrains a value to be a float.

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

FloatValue

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

Numeric Constraints

class valguard.constraints.NumericConstraint

Constrains a value to be numeric (an integer or float).

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

_NumericValue[int | float]

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

class valguard.constraints.BoundedIntConstraint(lower, upper)

Constrains a value to be an integer in a closed numeric interval.

This combines the checks of IntConstraint and IntervalConstraint.

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

IntValue

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

class valguard.constraints.BoundedFloatConstraint(lower, upper)

Constrains a value to be an integer in a closed numeric interval.

This combines the checks of IntConstraint and IntervalConstraint.

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

FloatValue

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

Interval & Literal Constraints

class valguard.constraints.IntervalConstraint(lower, upper)

Constrains a numeric value to lie in a closed interval.

property lower: float

same_interval(other)

Return type:

bool

property upper: float

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

_NumericValue[int | float]

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.

class valguard.constraints.LiteralStrConstraint(literals)

Constrains a string to lie within a chosen set of possibilities.

property literals: frozenset[str]

property literals_as_repr_string: str

validate(value)

Validate the given value, or raise a ValidationError.

Parameters:

value (object) – The Value instance to be validated.

Return type:

StrValue

Returns:

A type-cast version of the original value.

Raises:

ValidationError – If the value violates the constraint.