montepy._check_value module#

Utilities for checking values

Note

Some of this software was taken from OpenMC. See the LICENSE file for the specific licenses.

Classes:

CheckedList(expected_type, name[, items])

A list for which each element is type-checked as it's added

Functions:

args_checked(func)

A function decorator that enforces type annotations for the function when ran.

check_greater_than(func_name, name, value, ...)

Ensure that an object's value is greater than a given value.

check_increasing(func_name, name, value[, ...])

Ensure that a list's elements are strictly or loosely increasing.

check_length(func_name, name, value, length_min)

Ensure that a sized object has length within a given range.

check_less_than(func_name, name, value, maximum)

Ensure that an object's value is less than a given value.

check_type(func_name, name, value, expected_type)

Ensure that an object is of an expected type.

check_type_and_value(func_name, name, value, ...)

Check one argument's type and any Annotated value constraints.

check_type_iterable(func_name, name, value, ...)

Check a GenericAlias annotation (e.g. list[int], dict[str, int]).

check_value(func_name, name, value, ...)

Ensure that an object's value is contained in a set of acceptable values.
class montepy._check_value.CheckedList(expected_type, name, items=None)#

Bases: list

A list for which each element is type-checked as it’s added

Parameters:

  • expected_type (type or Iterable of type) – Type(s) which each element should be

  • name (str) – Name of data being checked

  • items (Iterable, optional) – Items to initialize the list with

Methods:

append(item)

Append item to list

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable, /)

Extend list by appending elements from the iterable.

index(value[, start, stop])

Return first index of value.

insert(index, item)

Insert item before index

pop([index])

Remove and return item at index (default last).

remove(value, /)

Remove first occurrence of value.

reverse()

Reverse IN PLACE.

sort(*[, key, reverse])

Sort the list in ascending order and return None.
append(item)#

Append item to list

Parameters:

item (object) – Item to append

clear()#

Remove all items from list.

copy()#

Return a shallow copy of the list.

count(value, /)#

Return number of occurrences of value.

extend(iterable, /)#

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

insert(index, item)#

Insert item before index

Parameters:

  • index (int) – Index in list

  • item (object) – Item to insert

pop(index=-1, /)#

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)#

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()#

Reverse IN PLACE.

sort(*, key=None, reverse=False)#

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

montepy._check_value.args_checked(func: Callable)#

A function decorator that enforces type annotations for the function when ran.

This will read the type annotations for all arguments and enforce that the argument is of that type at run-time. Value restrictions can also be applied as well with typing.Annotated.

Examples

This will ensure that all arguments have to be an integer,

>>> from montepy.utilities import *
>>> import montepy.types as ty
>>>
>>> @args_checked
... def foo(a: int) -> int:
...    return a
>>> print(foo(1))
1
>>> print(foo("a"))
Traceback (most recent call last):
...
TypeError: Unable to set "a" for "foo" to "a" which is not of type "int"

Values can be checked as by using typing.Annotated to add an annotation of the values that are allowed (via a special value checking function),

>>> import typing
>>> import montepy.types as ty
>>>
>>> @args_checked
... def bar(a: typing.Annotated[int, ty.positive]) -> int:
...     return a
>>> print(bar(1))
1
>>> print(bar(0))
Traceback (most recent call last):
...
ValueError: Unable to set "a" for "bar" to "0" since it is less than or equal to "0"
Parameters:

func (Callable) – The function to decorate

Returns:

A decorated function that will do type and value checking at run time based on the annotation.

Return type:

Callable

Raises:

  • TypeError – If an argument of the wrong type is provided

  • ValueError – If an argument of the right type, but wrong value is given.

montepy._check_value.check_greater_than(func_name, name, value, minimum, equality=False)#

Ensure that an object’s value is greater than a given value.

Parameters:

  • func_name (str) – The name of the function this was called from

  • name (str) – Description of the value being checked

  • value (object) – Object to check

  • minimum (object) – Minimum value to check against

  • equality (bool, optional) – Whether equality is allowed. Defaults to False.

montepy._check_value.check_increasing(func_name: str, name: str, value, equality: bool = False)#

Ensure that a list’s elements are strictly or loosely increasing.

Parameters:

  • func_name (str) – The name of the function this was called from

  • name (str) – Description of value being checked

  • value (Iterable) – Object to check if increasing

  • equality (bool) – Whether equality is allowed. Defaults to False.

montepy._check_value.check_length(func_name, name, value, length_min, length_max=None)#

Ensure that a sized object has length within a given range.

Parameters:

  • func_name (str) – The name of the function this was called from

  • name (str) – Description of value being checked

  • value (collections.abc.Sized) – Object to check length of

  • length_min (int) – Minimum length of object

  • length_max (int or None, optional) – Maximum length of object. If None, it is assumed object must be of length length_min.

montepy._check_value.check_less_than(func_name: str, name: str, value, maximum, equality=False)#

Ensure that an object’s value is less than a given value.

Parameters:

  • func_name (str) – The name of the function this was called from

  • name (str) – Description of the value being checked

  • value (object) – Object to check

  • maximum (object) – Maximum value to check against

  • equality (bool, optional) – Whether equality is allowed. Defaults to False.

montepy._check_value.check_type(func_name: str, name: str, value: Any, expected_type: GenericAlias, expected_iter_type: GenericAlias = None, *, none_ok: bool = False)#

Ensure that an object is of an expected type. Optionally, if the object is iterable, check that each element is of a particular type.

Parameters:

  • func_name (str) – The name of the function this was called from

  • name (str) – Description of value being checked

  • value (Any) – Object to check type of

  • expected_type (GenericAlias) – type to check object against

  • expected_iter_type (GenericAlias) – Expected type of each element in value, assuming it is iterable. If None, no check will be performed.

  • none_ok (bool) – Whether None is allowed as a value

montepy._check_value.check_type_and_value(func_name: str, name: str, value: Any, expected_type: GenericAlias, expected_iter_type: GenericAlias = None, *, none_ok: bool = False)#

Check one argument’s type and any Annotated value constraints.

Called by args_checked for each bound argument. Strips Annotated metadata (value-constraint callables from montepy.types, e.g. positive) from expected_type, delegates the bare type check to check_type(), then invokes each constraint callable in turn.

Parameters:

  • func_name (str) – Name of the decorated function, used in error messages.

  • name (str) – Argument name, used in error messages.

  • value (Any) – The argument value to validate.

  • expected_type (GenericAlias) – The annotation from the function signature. May be a plain type, a parameterised generic (e.g. list[int]), or an Annotated type whose extra args are constraint callables.

  • expected_iter_type (GenericAlias) – Expected element type when value is iterable.

  • none_ok (bool) – Whether None passes validation without further checks.

montepy._check_value.check_type_iterable(func_name: str, name: str, value: Any, expected_type: GenericAlias, *, none_ok: bool = False)#

Check a GenericAlias annotation (e.g. list[int], dict[str, int]).

Called internally by check_type() when it detects the annotation is a GenericAlias. Extracts the origin type and element-type arguments, then recurses into check_type_and_value() for each element.

Parameters:

  • func_name (str) – Name of the decorated function, used in error messages.

  • name (str) – Argument name, used in error messages.

  • value (Any) – The argument value to validate.

  • expected_type (GenericAlias) – A parameterised generic such as list[int] or dict[str, float].

  • none_ok (bool) – Whether None passes validation without further checks.

montepy._check_value.check_value(func_name: str, name: str, value: GenericAlias, accepted_values: Any)#

Ensure that an object’s value is contained in a set of acceptable values.

Parameters:

  • func_name (str) – The name of the function this was called from

  • name (str) – Description of value being checked

  • value (GenericAlias) – Object to check

  • accepted_values (Any) – Container of acceptable values