fix #832 : implemented TypedSession class (based on preliminary code written by gdementen)

Author: alixdamman

doc/source/api.rst

@@ -815,73 +815,21 @@ Load/Save
    Session.to_hdf
    Session.to_pickle
 
-.. _api-frozensession:
-
-FrozenSession
-=============
-
-.. autosummary::
-   :toctree: _generated/
-
-   FrozenSession
-
-Exploring
----------
-
-.. autosummary::
-   :toctree: _generated/
-
-   FrozenSession.names
-   FrozenSession.keys
-   FrozenSession.values
-   FrozenSession.items
-   FrozenSession.summary
-
-Copying
--------
-
-.. autosummary::
-   :toctree: _generated/
-
-   FrozenSession.copy
-
-Testing
--------
-
-.. autosummary::
-   :toctree: _generated/
-
-   FrozenSession.element_equals
-   FrozenSession.equals
-
-Selecting
----------
-
-.. autosummary::
-   :toctree: _generated/
-
-   FrozenSession.get
-
-Modifying
----------
+ArrayDef
+========
 
 .. autosummary::
    :toctree: _generated/
 
-   FrozenSession.apply
+   ArrayDef
 
-Load/Save
----------
+TypedSession
+============
 
 .. autosummary::
    :toctree: _generated/
 
-   FrozenSession.load
-   FrozenSession.save
-   FrozenSession.to_csv
-   FrozenSession.to_excel
-   FrozenSession.to_hdf
-   FrozenSession.to_pickle
+   TypedSession
 
 .. _api-editor:
 

larray/__init__.py

@@ -9,7 +9,7 @@
                                full_like, sequence, labels_array, ndtest, asarray, identity, diag,
                                eye, all, any, sum, prod, cumsum, cumprod, min, max, mean, ptp, var,
                                std, median, percentile, stack, zip_array_values, zip_array_items)
-from larray.core.session import Session, FrozenSession, local_arrays, global_arrays, arrays
+from larray.core.session import Session, TypedSession, ArrayDef, local_arrays, global_arrays, arrays
 from larray.core.constants import nan, inf, pi, e, euler_gamma
 from larray.core.metadata import Metadata
 from larray.core.ufuncs import wrap_elementwise_array_func, maximum, minimum, where
@@ -58,7 +58,7 @@
     'all', 'any', 'sum', 'prod', 'cumsum', 'cumprod', 'min', 'max', 'mean', 'ptp', 'var', 'std',
     'median', 'percentile', 'stack', 'zip_array_values', 'zip_array_items',
     # session
-    'Session', 'FrozenSession', 'local_arrays', 'global_arrays', 'arrays',
+    'Session', 'TypedSession', 'ArrayDef', 'local_arrays', 'global_arrays', 'arrays',
     # constants
     'nan', 'inf', 'pi', 'e', 'euler_gamma',
     # metadata

larray/core/session.py

@@ -11,9 +11,10 @@
 
 import numpy as np
 
+from larray.core.abstractbases import ABCArray
 from larray.core.metadata import Metadata
 from larray.core.group import Group
-from larray.core.axis import Axis
+from larray.core.axis import Axis, AxisCollection
 from larray.core.constants import nan
 from larray.core.array import Array, get_axes, ndtest, zeros, zeros_like, sequence, asarray
 from larray.util.misc import float_error_handler_factory, is_interactive_interpreter, renamed_to, inverseop
@@ -1393,87 +1394,85 @@ def display(k, v, is_metadata=False):
         return res
 
 
-# XXX: I wonder if we shouldn't create an AbstractSession instead of defining the _disabled()
-#      private method below.
-#      Auto-completion on any instance of a class that inherits from FrozenSession
-#      should not propose the add(), update(), filter(), transpose() and compact() methods
-class FrozenSession(Session):
-    """
-    The purpose of the present class is to be inherited by user defined classes where parameters
-    and variables of a model are defined (see examples below). These classes will allow users to
-    benefit from the so-called 'autocomplete' feature from development software such as PyCharm
-    (see the Notes section below) plus the main features of the :py:obj:`Session()` objects.
-
-    After creating an instance of a user defined 'session', some restrictions will be applied on it:
-
-    - **it is not possible to add or remove any parameter or variable,**
-    - **all non array variables (axes, groups, ...) cannot be modified,**
-    - **only values of array variables can be modified, not their axes.**
-
-    The reason of the first restriction is to avoid to select a deleted variable or
-    to miss an added one somewhere in the code when using the 'autocomplete' feature.
-    In other words, users can safely rely on the 'autocomplete' to write the model.
+class ArrayDef(ABCArray):
+    def __init__(self, axes):
+        if not all([isinstance(axis, (basestring, Axis)) for axis in axes]):
+            raise TypeError('ArrayDef only accepts string or Axis objects')
+        self.axes = axes
 
-    The reason of the second and third restrictions is to ensure the definition
-    of any variable or parameter to be constant throughout the whole code.
-    For example, a user don't need to remember that a new label has been added to
-    an axis of a given array somewhere earlier in the code (in a part of the model
-    written by a colleague). Therefore, these restrictions reduces the risk to deal
-    with unexpected error messages (like 'Incompatible Axes') and make it easier to
-    work in team.
-
-    Parameters
-    ----------
-    filepath: str, optional
-        Path where items have been saved. This can be either the path to a single file, a path to
-        a directory containing .csv files or a pattern representing several .csv files.
-    meta : list of pairs or dict or OrderedDict or Metadata, optional
-        Metadata (title, description, author, creation_date, ...) associated with the array.
-        Keys must be strings. Values must be of type string, int, float, date, time or datetime.
-
-    Notes
-    -----
-    The 'autocomplete' is a feature in which a software predicts the rest of a variable or function
-    name after a user typed the first letters. This feature allows users to use longer but meaningful
-    variable or function names (like 'population_be' instead of 'pbe') and to avoid creating an unwanted
-    new variable by misspelling the name of a given variable (e.g. typing 'poplation = something'
-    ('population' without u) will create a new variable instead of modifying the 'population' variable).
 
+# XXX: the name of the class below is not really important since it will serve as base
+#      for the LazySession and users are expected to inherit from the LazySession when
+#      they define their own classes
+class TypedSession(Session):
+    """
     Examples
     --------
-    >>> class ModelVariables(FrozenSession):
-    ...     LAST_AGE = 120
-    ...     FIRST_OBS_YEAR = 1991
-    ...     LAST_PROJ_YEAR = 2070
-    ...     AGE = Axis('age=0..{}'.format(LAST_AGE))
-    ...     GENDER = Axis('gender=male,female')
-    ...     TIME = Axis('time={}..{}'.format(FIRST_OBS_YEAR, LAST_PROJ_YEAR))
-    ...     CHILDREN = AGE[0:17]
-    ...     ELDERS = AGE[65:]
-    ...     population = zeros((AGE, GENDER, TIME))
-    ...     births = zeros((AGE, GENDER, TIME))
-    ...     deaths = zeros((AGE, GENDER, TIME))
-    >>> m = ModelVariables()
-    >>> m.names    # doctest: +NORMALIZE_WHITESPACE
-    ['AGE', 'CHILDREN', 'ELDERS', 'FIRST_OBS_YEAR', 'GENDER', 'LAST_AGE', 'LAST_PROJ_YEAR', 'TIME', 'births',
-    'deaths', 'population']
+    Content of file 'model_variables.py'
+
+    >>> # ==== MODEL VARIABLES ====
+    >>> class ModelVariables(TypedSession):
+    ...     FIRST_OBS_YEAR = int
+    ...     FIRST_PROJ_YEAR = int
+    ...     LAST_PROJ_YEAR = int
+    ...     AGE = Axis
+    ...     GENDER = Axis
+    ...     TIME = Axis
+    ...     G_CHILDREN = Group
+    ...     G_ADULTS = Group
+    ...     G_OBS_YEARS = Group
+    ...     G_PROJ_YEARS = Group
+    ...     population = ArrayDef(('AGE', 'GENDER', 'TIME'))
+    ...     births = ArrayDef(('AGE', 'GENDER', 'TIME'))
+    ...     deaths = ArrayDef(('AGE', 'GENDER', 'TIME'))
+
+    Content of file 'model.py'
+
+    >>> def run_model(variant_name, first_proj_year, last_proj_year):
+    ...     # create an instance of the ModelVariables class
+    ...     m = ModelVariables()
+    ...     # ==== setup variables ====
+    ...     # set scalars
+    ...     m.FIRST_OBS_YEAR = 1991
+    ...     m.FIRST_PROJ_YEAR = first_proj_year
+    ...     m.LAST_PROJ_YEAR = last_proj_year
+    ...     # set axes
+    ...     m.AGE = Axis('age=0..120')
+    ...     m.GENDER = Axis('gender=male,female')
+    ...     m.TIME = Axis('time={}..{}'.format(m.FIRST_OBS_YEAR, m.LAST_PROJ_YEAR))
+    ...     # set groups
+    ...     m.G_CHILDREN = m.AGE[:17]
+    ...     m.G_ADULTS = m.AGE[18:]
+    ...     m.G_OBS_YEARS = m.TIME[:m.FIRST_PROJ_YEAR-1]
+    ...     m.G_PROJ_YEARS = m.TIME[m.FIRST_PROJ_YEAR:]
+    ...     # set arrays
+    ...     m.population = zeros((m.AGE, m.GENDER, m.TIME))
+    ...     m.births = zeros((m.AGE, m.GENDER, m.TIME))
+    ...     m.deaths = zeros((m.AGE, m.GENDER, m.TIME))
+    ...     # ==== model ====
+    ...     # some code here
+    ...     # ...
+    ...     # ==== output ====
+    ...     # save all variables in an HDF5 file
+    ...     m.save('{variant_name}.h5', display=True)
+
+    Content of file 'main.py'
+
+    >>> run_model('proj_2020_2070', first_proj_year=2020, last_proj_year=2070)
+    dumping FIRST_OBS_YEAR ... Cannot dump FIRST_OBS_YEAR. int is not a supported type
+    dumping FIRST_PROJ_YEAR ... Cannot dump FIRST_PROJ_YEAR. int is not a supported type
+    dumping LAST_PROJ_YEAR ... Cannot dump LAST_PROJ_YEAR. int is not a supported type
+    dumping AGE ... done
+    dumping GENDER ... done
+    dumping TIME ... done
+    dumping G_CHILDREN ... done
+    dumping G_ADULTS ... done
+    dumping G_OBS_YEARS ... done
+    dumping G_PROJ_YEARS ... done
+    dumping population ... done
+    dumping births ... done
+    dumping deaths ... done
     """
-    def __init__(self, filepath=None, meta=None):
-        # feed the kwargs dict with all items declared as class attributes
-        kwargs = {}
-        for key, value in vars(self.__class__).items():
-            if not key.startswith('_'):
-                kwargs[key] = value
-
-        if meta:
-            kwargs['meta'] = meta
-
-        Session.__init__(self, **kwargs)
-        object.__setattr__(self, 'add', self._disabled)
-
-        if filepath:
-            self.load(filepath)
-
     def __setitem__(self, key, value):
         self._check_key_value(key, value)
 
@@ -1494,53 +1493,35 @@ def _check_key_value(self, key, value):
         cls = self.__class__
         attr_def = getattr(cls, key, None)
         if attr_def is None:
-            raise ValueError("The '{item}' item has not been found in the '{cls}' class declaration. "
-                             "Adding a new item after creating an instance of the '{cls}' class is not permitted."
-                             .format(item=key, cls=cls.__name__))
-        if (isinstance(value, (int, float, basestring, np.generic)) and value != attr_def) \
-                or (isinstance(value, (Axis, Group)) and not value.equals(attr_def)):
-            raise TypeError("The '{key}' item is of kind '{cls_name}' which cannot by modified."
-                            .format(key=key, cls_name=attr_def.__class__.__name__))
-        if type(value) != type(attr_def):
-            raise TypeError("Expected object of type '{attr_cls}'. Got object of type '{value_cls}'."
-                            .format(attr_cls=attr_def.__class__.__name__, value_cls=value.__class__.__name__))
-        if isinstance(attr_def, Array):
-            try:
-                attr_def.axes.check_compatible(value.axes)
-            except ValueError as e:
-                msg = str(e).replace("incompatible axes:", "Incompatible axes for array '{key}':".format(key=key))
-                raise ValueError(msg)
-        elif isinstance(value, np.ndarray) and value.shape != attr_def.shape:
-            raise ValueError("Incompatible shape for Numpy array '{key}'. "
-                             "Expected shape {attr_shape} but got {value_shape}."
-                             .format(key=key, attr_shape=attr_def.shape, value_shape=value.shape))
+            warnings.warn("'{}' is not declared in '{}'".format(key, self.__class__.__name__), stacklevel=2)
+        else:
+            attr_type = Array if isinstance(attr_def, ArrayDef) else attr_def
+            if not isinstance(value, attr_type):
+                raise TypeError("Expected object of type '{}'. Got object of type '{}'."
+                                .format(attr_type.__name__, value.__class__.__name__))
+            if isinstance(attr_def, ArrayDef):
+                def get_axis(axis):
+                    if isinstance(axis, basestring):
+                        try:
+                            axis = getattr(self, axis)
+                        except AttributeError:
+                            raise ValueError("Axis '{}' not defined in '{}'".format(axis, self.__class__.__name__))
+                    return axis
+
+                defined_axes = AxisCollection([get_axis(axis) for axis in attr_def.axes])
+                try:
+                    defined_axes.check_compatible(value.axes)
+                except ValueError as error:
+                    msg = str(error).replace("incompatible axes:", "incompatible axes for array '{}':".format(key))\
+                        .replace("vs", "was declared as")
+                    raise ValueError(msg)
 
     def copy(self):
         instance = self.__class__()
         for key, value in self.items():
             instance[key] = copy(value)
         return instance
 
-    def apply(self, func, *args, **kwargs):
-        kind = kwargs.pop('kind', Array)
-        instance = self.__class__()
-        for key, value in self.items():
-            instance[key] = func(value, *args, **kwargs) if isinstance(value, kind) else value
-        return instance
-
-    def _disabled(self, *args, **kwargs):
-        """This method will not work because adding or removing item and modifying axes of declared arrays
-        is not permitted."""
-        raise ValueError(
-            "Adding or removing item and modifying axes of declared arrays is not permitted.".format(
-                cls=self.__class__.__name__
-            )
-        )
-
-    # XXX: not sure we should or not disable 'transpose()'?
-    __delitem__ = __delattr__ = _disabled
-    update = filter = transpose = compact = _disabled
-
 
 def _exclude_private_vars(vars_dict):
     return {k: v for k, v in vars_dict.items() if not k.startswith('_')}