updated documentation and doctests of CheckedArray and CheckedSession classes

Author: alixdamman

larray/core/checked.py

@@ -78,16 +78,16 @@ def CheckedArray(axes: AxisCollection, dtype: np.dtype = float) -> Type[Array]:
         #      to get autocompletion from PyCharm
         from larray.core.checked import CheckedArrayImpl
         """
-        Represents a constrained array.
+        Represents a checked array.
         Its axes are assumed to be "frozen", meaning they are constant all along the execution of the program.
         A constraint on the dtype of the data can be also specified.
 
         Parameters
         ----------
         axes: AxisCollection
-            Axes of the constrained array.
+            Axes of the checked array.
         dtype: data-type, optional
-            Data-type for the constrained array. Defaults to float.
+            Data-type for the checked array. Defaults to float.
 
         Returns
         -------
@@ -195,12 +195,11 @@ class CheckedSession(Session, AbstractCheckedSession, metaclass=ModelMetaclass):
         This class is intended to be inherited by user defined classes in which the variables of a model are declared.
         Each declared variable is constrained by a type defined explicitly or deduced from the given default value
         (see examples below).
-        All classes inheriting from `CheckedSession` will have access to all methods of the
-        :py:class:`Session` class.
+        All classes inheriting from `CheckedSession` will have access to all methods of the :py:class:`Session` class.
 
-        The special :py:funct:`ConstantAxesArray` type represents an Array object with constant axes.
-        This prevents users from modifying the dimensions and/or labels of an array by mistake and make sure that
-        the definition of an array remains always valid in the model.
+        The special :py:funct:`CheckedArray` type represents an Array object with fixed axes and/or dtype.
+        This prevents users from modifying the dimensions (and labels) and/or the dtype of an array by mistake
+        and make sure that the definition of an array remains always valid in the model.
 
         By declaring variables, users will speed up the development of their models using the auto-completion
         (the feature in which development tools like PyCharm try to predict the variable or function a user intends
@@ -254,20 +253,20 @@ class CheckedSession(Session, AbstractCheckedSession, metaclass=ModelMetaclass):
         ...     births: Array
         ...     # --- declare variables with a default value ---
         ...     # The default value will be used to set the variable if no value is passed at instantiation (see below).
-        ...     # Such variable will be constrained by the type deduced from its default value.
-        ...     target_age: Group = AGE[:2] >> '0-2'
+        ...     # Their type is deduced from their default value and cannot be changed at runtime.
+        ...     target_age = AGE[:2] >> '0-2'
         ...     population = zeros((AGE, GENDER, TIME), dtype=int)
-        ...     # --- declare constrained arrays ---
-        ...     # the constrained arrays have axes assumed to be "frozen", meaning they are
+        ...     # --- declare checked arrays ---
+        ...     # The checked arrays have axes assumed to be "frozen", meaning they are
         ...     # constant all along the execution of the program.
         ...     mortality_rate: CheckedArray((AGE, GENDER))
-        ...     # for constrained arrays, the default value can be given as a scalar.
-        ...     # A dtype can be also optionally specified (defaults to float).
+        ...     # For checked arrays, the default value can be given as a scalar.
+        ...     # Optionally, a dtype can be also specified (defaults to float).
         ...     deaths: CheckedArray((AGE, GENDER, TIME), dtype=int) = 0
 
-        >>> variant_name = 'variant_1'
-        >>> # instantiation --> create an instance of the ModelVariables class
-        >>> # all variables declared without a default value must be set
+        >>> variant_name = "baseline"
+        >>> # Instantiation --> create an instance of the ModelVariables class.
+        >>> # Warning: All variables declared without a default value must be set.
         >>> m = ModelVariables(
         ...                   variant_name = variant_name,
         ...                   birth_rate = zeros((AGE, GENDER)),
@@ -276,8 +275,17 @@ class CheckedSession(Session, AbstractCheckedSession, metaclass=ModelMetaclass):
         ...                   )
 
         >>> # ==== model ====
-        >>> # axes and dtype of arrays 'birth_rate', 'births' and 'population' are not protected,
-        >>> # leading to potentially unexpected behavior of the model.
+        >>> # In the definition of ModelVariables, the 'birth_rate' variable, has been declared as an Array object.
+        >>> # This means that the 'birth_rate' variable will always remain of type Array.
+        >>> # Any attempt to assign a non-Array value to 'birth_rate' will make the program to crash.
+        >>> m.birth_rate = Array([0.045, 0.055], GENDER)    # OK
+        >>> m.birth_rate = [0.045, 0.055]                   # Fails
+        Traceback (most recent call last):
+            ...
+        pydantic.errors.ArbitraryTypeError: instance of Array expected
+        >>> # However, the arrays 'birth_rate', 'births' and 'population' have not been declared as 'CheckedArray'.
+        >>> # Thus, axes and dtype of these arrays are not protected, leading to potentially unexpected behavior
+        >>> # of the model.
         >>> # example 1: Let's say we want to calculate the new births for the year 2025 and we assume that
         >>> # the birth rate only differ by gender.
         >>> # In the line below, we add an additional TIME axis to 'birth_rate' while it was initialized
@@ -335,7 +343,7 @@ class CheckedSession(Session, AbstractCheckedSession, metaclass=ModelMetaclass):
         dtype: int32
         memory used: 968 bytes
 
-        >>> # note that it still possible to add undeclared variables to a constrained session
+        >>> # note that it still possible to add undeclared variables to a checked session
         >>> # but this must be done with caution.
         >>> m.undeclared_var = 'undeclared_var'
 
@@ -345,9 +353,9 @@ class CheckedSession(Session, AbstractCheckedSession, metaclass=ModelMetaclass):
         dumping variant_name ... done
         dumping birth_rate ... done
         dumping births ... done
-        dumping target_age ... done
         dumping mortality_rate ... done
         dumping deaths ... done
+        dumping target_age ... done
         dumping population ... done
         dumping undeclared_var ... done
         """