fix #832 : implemented FrozenSession class

Author: alixdamman

doc/source/api.rst

@@ -790,7 +790,6 @@ Modifying
 
    Session.add
    Session.update
-   Session.get
    Session.apply
    Session.transpose
 
@@ -816,6 +815,74 @@ 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
+---------
+
+.. autosummary::
+   :toctree: _generated/
+
+   FrozenSession.apply
+
+Load/Save
+---------
+
+.. autosummary::
+   :toctree: _generated/
+
+   FrozenSession.load
+   FrozenSession.save
+   FrozenSession.to_csv
+   FrozenSession.to_excel
+   FrozenSession.to_hdf
+   FrozenSession.to_pickle
+
 .. _api-editor:
 
 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, local_arrays, global_arrays, arrays
+from larray.core.session import Session, FrozenSession, 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', 'local_arrays', 'global_arrays', 'arrays',
+    'Session', 'FrozenSession', 'local_arrays', 'global_arrays', 'arrays',
     # constants
     'nan', 'inf', 'pi', 'e', 'euler_gamma',
     # metadata

larray/core/session.py

@@ -6,6 +6,7 @@
 import re
 import fnmatch
 import warnings
+from copy import copy
 from collections import OrderedDict
 
 import numpy as np
@@ -92,7 +93,7 @@ def __init__(self, *args, **kwargs):
 
         if len(args) == 1:
             a0 = args[0]
-            if isinstance(a0, str):
+            if isinstance(a0, basestring):
                 # assume a0 is a filename
                 self.load(a0)
             else:
@@ -1392,6 +1393,155 @@ 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.
+
+    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).
+
+    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']
+    """
+    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)
+
+        # we need to keep the attribute in sync (initially to mask the class attribute)
+        object.__setattr__(self, key, value)
+        self._objects[key] = value
+
+    def __setattr__(self, key, value):
+        if key != 'meta':
+            self._check_key_value(key, value)
+
+        # update the real attribute
+        object.__setattr__(self, key, value)
+        # update self._objects
+        Session.__setattr__(self, key, value)
+
+    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))
+
+    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('_')}