simplebench.validators.misc module🔗

Utility functions for validating arguments to attribute setters and constructors.

These functions raise appropriate exceptions with error tags from exceptions.py and return the validated and/or normalized value.

simplebench.validators.misc.validate_filename(filename: Any) → str[source]🔗

Validate a filename for use in the filesystem.

It validates that:

The filename is a string.
The filename suffix (if present) is alphanumeric and no longer than 10 characters.
The filename stem (name without suffix) is made of alphanumeric characters, underscores, or dashes, and is at least one character long.
The filename stem does not start or end with an underscore or dash.
The total filename length does not exceed 255 characters.

Parameters:

filename (str) – The filename to validate.

Returns:

The validated filename.

Return type:

str

Raises:

SimpleBenchTypeError – If the filename is not a string.
SimpleBenchValueError – If the filename is invalid.

simplebench.validators.misc.validate_float( value: Any, field_name: str, type_tag: ErrorTag, ) → float[source]🔗

Validate that a value is a float or integer.

Validates that the value is either a float or an int. The return type is always a float.

Parameters:

value (float | int) – The value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.

Returns:

The validated float.

Return type:

float

Raises:

SimpleBenchTypeError – If the value is not a float.

simplebench.validators.misc.validate_float_range( number: Any, field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, min_value: float, max_value: float, ) → float[source]🔗

Validate that a value is a float within a specified range.

Parameters:

number (float) – The value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.
min_value (float) – The minimum value of the range.
max_value (float) – The maximum value of the range.

Raises:

SimpleBenchValueError – If min_value is greater than max_value.
SimpleBenchTypeError – If field_name is not a str.
SimpleBenchTypeError – If type_tag or value_tag is not an ErrorTag.
SimpleBenchTypeError – If number, min_value, or max_value is not a float..
SimpleBenchValueError – If number is not within the specified range.

simplebench.validators.misc.validate_frozenset_of_type( value: frozenset[Any], types: type[T], field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, allow_empty: bool = True, ) → frozenset[T][source]🔗

simplebench.validators.misc.validate_frozenset_of_type( value: frozenset[Any], types: tuple[type, ...], field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, allow_empty: bool = True, ) → frozenset[Any]

Validate that a value is a frozenset of specified type(s).

When a single type is provided, the return type is automatically inferred as frozenset[T]. When multiple types are provided, the return type is frozenset[Any], which allows the caller to narrow the type with an explicit annotation.

Single type (automatic type inference) example:

friends_names: frozenset[str] = frozenset(['Alice', 'Bob'])
names = validate_frozenset_of_type(
    friends_names, str, 'names',
    ErrorTag.SOME_TYPE_TAG,
    ErrorTag.SOME_VALUE_TAG,
    allow_empty=False
)
# Type: frozenset[str]

Multiple types (manual narrowing) example:

mixed_values: frozenset[str | int] = frozenset(['a', 1, 'b', 2])
mixed: frozenset[str | int] = validate_frozenset_of_type(
    mixed_values, (str, int), 'items',
    ErrorTag.SOME_TYPE_TAG,
    ErrorTag.SOME_VALUE_TAG,
    allow_empty=True)
# Type: frozenset[str | int]

Parameters:

value (Any) – The frozenset of values to validate.
types (type[T] | tuple[type, ...]) – A single type or tuple of allowed types.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.
allow_empty (bool) – Whether to allow an empty iterable. Defaults to True.

Returns:

For single type, returns frozenset[T]. For multiple types, returns frozenset[Any] which can be narrowed with explicit type annotation.

Return type:

frozenset

Raises:

SimpleBenchTypeError – If the value is not a frozenset or contains invalid types.
SimpleBenchValueError – If the frozenset is empty and allow_empty is False.

simplebench.validators.misc.validate_int( value: Any, field_name: str, type_tag: ErrorTag, ) → int[source]🔗

Validate that a value is an integer.

Parameters:

value (int) – The value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.

Returns:

The validated integer.

Return type:

int

Raises:

SimpleBenchTypeError – If the value is not an integer.

simplebench.validators.misc.validate_int_range( number: Any, field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, min_value: int, max_value: int, ) → int[source]🔗

Validate that a value is an integer within a specified range.

Parameters:

number (Any) – The value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.
min_value (int) – The minimum value of the range.
max_value (int) – The maximum value of the range.

Raises:

SimpleBenchValueError – If min_value is greater than max_value.
SimpleBenchTypeError – If field_name is not a str.
SimpleBenchTypeError – If type_tag or value_tag is not an ErrorTag.
SimpleBenchTypeError – If number, min_value, or max_value is not an int.
SimpleBenchValueError – If number is not within the specified range.

simplebench.validators.misc.validate_non_blank_string( value: Any, field_name: str, type_error_tag: ErrorTag, value_error_tag: ErrorTag, ) → str[source]🔗

Validate and normalize a non-blank string field.

Any leading or trailing whitespace is stripped from the string before returning it.

The validation checks that the value is a string and that it is not blank or only whitespace. The returned value is guaranteed to be non-blank and non-blank and to be of type str.

Parameters:

value (str) – The string value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_error_tag (ErrorTag) – The error tag to use for type errors.
value_error_tag (ErrorTag) – The error tag to use for value errors.

Returns:

The stripped string value.

Return type:

str

Raises:

SimpleBenchTypeError – If the value is not a string.
SimpleBenchValueError – If the string is blank or only whitespace.

simplebench.validators.misc.validate_non_blank_string_or_is_none( value: Any, field_name: str, type_error_tag: ErrorTag, value_error_tag: ErrorTag, allow_none: bool = True, ) → str | None[source]🔗

Validate and normalize a non-blank string field.

Any leading or trailing whitespace is stripped from the string before returning it. The validation checks that the value is a string and that it is not blank or only whitespace. If the value is None and allow_none is True, None is returned.

The validated value is guaranteed to either be non-blank and non-blank and of type str, or None if allow_none is True and None is provided as the value.

Parameters:

value (str) – The string value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_error_tag (ErrorTag) – The error tag to use for type errors.
value_error_tag (ErrorTag) – The error tag to use for value errors.
allow_none (bool) – Whether to allow None as a valid value. Defaults to True.

Returns:

The stripped string value or None if allowed and provided.

Return type:

str | None

Raises:

SimpleBenchTypeError – If the value is not a str, or None (if allow_none is False).
SimpleBenchValueError – If the string is blank or only whitespace.

simplebench.validators.misc.validate_non_negative_float( value: float | int, field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, ) → float[source]🔗

Validate that a value is a non-negative float or integer.

Validates that the value is either a float or an int and that it is non-negative. The return type is always a float.

Parameters:

value (float | int) – The value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.

Returns:

The validated non-negative float.

Return type:

float

Raises:

SimpleBenchTypeError – If the value is not a float.
SimpleBenchValueError – If the value is negative.

simplebench.validators.misc.validate_non_negative_int( value: Any, field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, ) → int[source]🔗

Validate that a value is a non-negative integer.

Parameters:

value (int) – The value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.

Returns:

The validated non-negative integer.

Return type:

int

Raises:

SimpleBenchTypeError – If the value is not an integer.
SimpleBenchValueError – If the value is negative.

simplebench.validators.misc.validate_positive_float( value: Any, field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, ) → float[source]🔗

Validate that a value is a positive float or integer.

Validates that the value is either a float or an int and that it is positive. The return type is always a float.

Parameters:

value (float | int) – The value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.

Returns:

The validated positive float.

Return type:

float

Raises:

SimpleBenchTypeError – If the value is not a float.
SimpleBenchValueError – If the value is not positive.

simplebench.validators.misc.validate_positive_int( value: Any, field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, ) → int[source]🔗

Validate that a value is a positive integer.

Parameters:

value (int) – The value to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.

Returns:

The validated positive integer.

Return type:

int

Raises:

SimpleBenchTypeError – If the value is not an integer.
SimpleBenchValueError – If the value is not positive.

simplebench.validators.misc.validate_sequence_of_numbers( value: Sequence[int | float], field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, allow_empty: bool = True, ) → Sequence[int | float][source]🔗

Validate that a value is a sequence of numbers (ints or floats).

Because this function checks for Sequence[int | float], it will accept lists, tuples, sets, and other sequence types, but not str or bytes.

The type declaration for the value argument and return type is Sequence[int | float] to indicate that the sequence should contain a mix of ints and/or floats.

Because this is a validation function, the actual type of the value argument can be and static type checkers may warn if the caller does not pass a value that is already declared as Sequence[int | float]. This is acceptable because the purpose of this function is to validate the type and contents of the value argument - the warnings from the type checkers are synergetic with the purpose of this function.

Because the returned value is declared to be a Sequence of int or float, this has the effect of narrowing the type for callers that use type checkers.

If you wish to suppress static type checker warnings for a specific call to this function, you can use a type: ignore[arg-type] comment on that line.

Parameters:

value (Sequence[int | float]) – The sequence of values to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.
allow_empty (bool) – Whether to allow a empty sequence. Defaults to True.

Returns:

The validated Sequence of numbers.

Return type:

Sequence[int | float]

Raises:

SimpleBenchTypeError – If the value is not a sequence or contains non-numeric types.
SimpleBenchValueError – If the sequence is empty and allow_empty is False.

simplebench.validators.misc.validate_sequence_of_str( value: Any, field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, *, allow_empty: bool = True, allow_blank: bool = True, allow_whitespace: bool = True, ) → list[str][source]🔗

Validate that a value is a sequence of strings.

This function checks that the input is a sequence (list, tuple, etc.) of strings, and that each string meets the specified criteria.

It can enforce that the sequence is not empty, and that individual strings are not blank or do not contain any whitespace, based on the provided flags.

Parameters:

value (Sequence[Any]) – The sequence of values to validate.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.
allow_empty (bool) – Whether to allow an empty sequence. Defaults to True.
allow_blank (bool) – Whether to allow blank strings in the sequence. Defaults to True.
allow_whitespace (bool) – Whether to allow strings that contain whitespace. Defaults to True.

Returns:

The validated list of strings.

Return type:

list[str]

Raises:

SimpleBenchTypeError – If the value is not a sequence or contains non-string types.
SimpleBenchValueError – If the sequence is empty and allow_empty is False or an element is blank and allow_blank is False.

simplebench.validators.misc.validate_sequence_of_type( value: Any, types: type[T], field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, *, allow_empty: bool = True, ) → list[T][source]🔗

simplebench.validators.misc.validate_sequence_of_type( value: Any, types: tuple[type, ...], field_name: str, type_tag: ErrorTag, value_tag: ErrorTag, *, allow_empty: bool = True, ) → list[Any]

Validate that a value is a sequence of specified type(s).

When a single type is provided, the return type is automatically inferred as list[T]. When multiple types are provided, the return type is list[Any], which allows the caller to narrow the type with an explicit annotation.

Parameters:

value (Sequence[Any]) – The sequence of values to validate.
types (type[T] | tuple[type, ...] | LazyType[T, Any]) – A single type or tuple of allowed types.
field_name (str) – The name of the field being validated (for error messages).
type_tag (ErrorTag) – The error tag to use for type errors.
value_tag (ErrorTag) – The error tag to use for value errors.
allow_empty (bool) – Whether to allow an empty sequence. Defaults to True.

Returns:

For single type, returns list[T]. For multiple types, returns list[Any] which can be narrowed with explicit type annotation.

Return type:

list[T] | list[Any]

Raises:

SimpleBenchTypeError – If the value is not a sequence or contains invalid types.
SimpleBenchValueError – If the sequence is empty and allow_empty is False.

Examples

Single type (automatic inference):

names = validate_sequence_of_type(['Alice'], str, 'names', ...)
# Type: list[str]

Multiple types (manual narrowing):

mixed: list[str | int] = validate_sequence_of_type(
    ['a', 1], (str, int), 'items', ...
)
# Type: list[str | int]