simplebench.validators package🔗

Validator functions for SimpleBench.

simplebench.validators.validate_bool(
value: Any,
name: str,
error_tag: ErrorTag,
*,
allow_none: bool = False,
) → bool | None[source]🔗

Validate that a value is a boolean.

If allow_none is True, None is also accepted.

If the allow_none parameter is not provided, it defaults to False and only boolean values are accepted. In that case, the return type is guaranteed to be bool and type checkers will accept it as bool for type narrowing.

Parameters:

  • value (Any) – The value to validate.

  • name (str) – The name of the field being validated (for error messages).

  • error_tag (ErrorTag) – The error tag to use for type errors.

  • allow_none (bool) – Whether to allow None as a valid value.

Returns:

The validated boolean or None if allowed and provided.

Return type:

bool | None

Raises:

SimpleBenchTypeError –

  • If the value is not a boolean and allow_none==False

  • If the value is not a boolean or None and allow_none==True

  • If name is not a str

  • If error_tag is not an ErrorTag

  • If allow_none is not a bool

simplebench.validators.validate_dirpath(
dirpath: Any,
allow_empty: bool = False,
) → str[source]🔗

Validate a directory path for use in the filesystem.

It validates that:

  • The directory path is a string.

  • The complete directory path is no longer than 255 characters.

  • The directory path does not contain characters other than alphanumeric characters (A-Za-z0-9), underscores (-), dashes (-), slashes ( / ), or backslashes ( ).

  • That individual directory path element names do not start or end with a dash (-) or underscore (_).

  • That individual directory path element names are at least one character long but no longer than 64 characters. (this does not apply to the full path, only to each element between slashes or backslashes and is checked separately).

  • If allow_empty is False, that the directory path is not an empty string. If allow_empty is True, an empty string is considered to be a valid dirpath (default is False).

Backslashes ( ) are converted to slashes ( / ) for validation purposes.

Parameters:

  • dirpath (str) – The directory path to validate.

  • allow_empty (bool) – Whether to allow an empty directory path. Defaults to False.

Returns:

The validated directory path.

Return type:

str

Raises:
simplebench.validators.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:
simplebench.validators.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.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:
simplebench.validators.validate_frozenset_of_type(
value: frozenset[Any],
types: type[T] | tuple[type, ...],
field_name: str,
type_tag: ErrorTag,
value_tag: ErrorTag,
allow_empty: bool = True,
) → frozenset[T] | frozenset[Any][source]🔗

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:
simplebench.validators.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.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:
simplebench.validators.validate_iterable_of_type(
value: Any,
types: type[T] | tuple[type, ...],
field_name: str,
type_tag: ErrorTag,
value_tag: ErrorTag,
*,
allow_empty: bool = True,
exact_type: bool = False,
) → list[T] | list[Any][source]🔗

Validate that a value is an iterable 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 (Iterable[Any]) – The iterable 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.

  • exact_type (bool) – If set to True, require that the types be exactly the types specified, not subclasses. Otherwise allow subclass matches.

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:

Examples

Single type (automatic inference):

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

Multiple types (manual narrowing):

mixed: list[str | int] = validate_iterable_of_type(
    ['a', 1], (str, int), 'items', ...
)
# Type: list[str | int]
simplebench.validators.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:
simplebench.validators.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:
simplebench.validators.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:
simplebench.validators.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:
simplebench.validators.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:
simplebench.validators.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:
simplebench.validators.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:
simplebench.validators.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.validate_sequence_of_type(
value: Any,
types: type[T] | tuple[type, ...],
field_name: str,
type_tag: ErrorTag,
value_tag: ErrorTag,
*,
allow_empty: bool = True,
exact_type: bool = False,
) → list[T] | list[Any][source]🔗

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, ...]) – 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) – If set to True, allow an empty sequence. Otherwise raise an error.

  • exact_type (bool) – If set to True, require that the types be exactly the types specified, not subclasses. Otherwise allow subclass matches.

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:

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]
simplebench.validators.validate_string(
value: Any,
field_name: str,
type_error_tag: ErrorTag,
value_error_tag: ErrorTag,
*,
strip: bool = False,
allow_empty: bool = True,
allow_blank: bool = True,
alphanumeric_only: bool = False,
) → str[source]🔗

Validate and normalize a string field.

Validates that the value is a string. Optionally strips leading/trailing whitespace, checks for emptiness, blankness (whitespace-only strings), and alphanumeric content.

The returned value is guaranteed to be of type str and acts to type-narrow the returned value.

Following the principle of ‘least astonishment’, the validator does not modify the input string unless strip=True is set. If strip=True is set, the string is stripped of leading and trailing whitespace before other checks are applied.

Explanation of options:

strip=True means leading/trailing whitespace is removed before other checks. allow_empty=True means the string cannot be empty (“”). allow_blank=True means the string can contain only whitespace characters. alphanumeric_only=True means the string only contain alphanumeric characters (a-z, A-Z, 0-9).

Interaction of options:

If strip=True, allow_empty=True, allow_blank=False is provided, allow_empty=False takes precedence over allow_blank=True as the more specific check. Therefore ‘ ‘ would be stripped to ‘’ and then accepted as empty.

If strip=True, allow_blank=True, allow_empty=False is provided, allow_empty=False takes precedence over allow_blank=True because after stripping a blank string becomes an empty string and allow_empty=False is the more specific check. Therefore ‘ ‘ would be stripped to ‘’ and then rejected as empty.

If strip=False, allow_blank=True, alphanumeric_only=True is provided, alphanumeric_only=True takes precedence over allow_blank=True because a blank string with whitespace is not alphanumeric by definition.

alphanumeric_only=True behaves differently than str().isalnum() in that it allows empty strings if allow_empty=True is also provided.

Parameters:

  • value (Any) – The value to validate as being a string.

  • 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.

  • strip (bool) – Whether to strip leading/trailing whitespace.

  • allow_empty (bool) – Whether to allow empty strings.

  • allow_blank (bool) – Whether to allow blank strings (strings that consist only of whitespace).

  • alphanumeric_only (bool) – Whether to allow only alphanumeric characters.

Raises:
simplebench.validators.validate_type(
value: Any,
types: type[T] | tuple[type | LazyTypeProxy[Any], ...] | LazyTypeProxy[T],
field_name: str,
error_tag: ErrorTag,
) → T | Any[source]🔗

Validate that a value is of the expected type.

The returned value is guaranteed to be of type expected and acts to type-narrow the returned value for static type checking if a single type is provided.

If multiple types are provided in a tuple for the expected type, the caller can type-narrow the type of the returned type by declaring the untupled types by assigning the return value to a variable with an explicit type annotation.

The value itself is always returned unchanged if it passes the validation.

Example

mixed: str | int = validate_type(
    value=some_value,
    expected=(str, int),
    name='mixed',
    error_tag=ErrorTag.INVALID_EXPECTED_ARG_TYPE)
Parameters:

  • value (Any) – The value to validate.

  • types (type[T] | tuple[type, ...] | LazyType[T]) – The expected type of the value.

  • field_name (str) – The name of the field being validated (for error messages).

  • error_tag (ErrorTag) – The error tag to use for type errors.

Returns:

The validated (unmodifed) value.

Return type:

T | Any

Raises:

SimpleBenchTypeError – If the value is not of the expected type.

Subpackages🔗

Submodules🔗