>> simplified ModelMetaclass.__new__()

>> fix larray-project#866 : added Parameters class

Author: alixdamman

doc/source/api.rst

@@ -815,13 +815,13 @@ Load/Save
    Session.to_hdf
    Session.to_pickle
 
-ArrayDef
-========
+ConstrainedArray
+================
 
 .. autosummary::
    :toctree: _generated/
 
-   ArrayDef
+   ConstrainedArray
 
 ConstrainedSession
 ==================
@@ -831,6 +831,14 @@ ConstrainedSession
 
    ConstrainedSession
 
+Parameters
+==========
+
+.. autosummary::
+   :toctree: _generated/
+
+   Parameters
+
 .. _api-editor:
 
 Editor

larray/__init__.py

@@ -10,7 +10,7 @@
                                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.constrained import ConstrainedSession, ConstrainedArray
+from larray.core.constrained import ConstrainedArray, ConstrainedSession, Parameters
 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
@@ -61,7 +61,7 @@
     # session
     'Session', 'local_arrays', 'global_arrays', 'arrays',
     # constrained
-    'ConstrainedSession', 'ConstrainedArray',
+    'ConstrainedArray', 'ConstrainedSession', 'Parameters',
     # constants
     'nan', 'inf', 'pi', 'e', 'euler_gamma',
     # metadata

larray/core/constrained.py

@@ -4,14 +4,12 @@
 
 import numpy as np
 
+from types import FunctionType
 from typing import TYPE_CHECKING, Type, Optional, Any, Union, Dict, Set, List, Tuple, Callable, no_type_check
 
 from pydantic.fields import ModelField, Undefined
 from pydantic.class_validators import extract_validators, Validator
 from pydantic.typing import is_classvar, resolve_annotations
-from pydantic.types import PyObject
-from pydantic.utils import validate_field_name, lenient_issubclass
-from pydantic.main import UNTOUCHED_TYPES, inherit_config, is_valid_field
 
 from larray.core.metadata import Metadata
 from larray.core.axis import AxisCollection
@@ -168,12 +166,11 @@ def inherit_validators(base_validators: Dict[str, List[Validator]],
         for base in reversed(bases):
             if issubclass(base, ConstrainedSession) and base != ConstrainedSession:
                 fields.update(deepcopy(base.__fields__))
-                config = inherit_config(base.__config__, config)
                 validators = inherit_validators(base.__validators__, validators)
 
-        config = inherit_config(namespace.get('Config'), config)
         validators = inherit_validators(extract_validators(namespace), validators)
 
+        # update fields inherited from base classes
         for field in fields.values():
             field.set_config(config)
             extra_validators = validators.get(field.name, [])
@@ -182,22 +179,34 @@ def inherit_validators(base_validators: Dict[str, List[Validator]],
                 # re-run prepare to add extra validators
                 field.populate_validators()
 
+        untouched_types = (FunctionType, property, type, classmethod, staticmethod)
+
+        def validate_field_name(bases: List[Any], field_name: str) -> None:
+            """
+            Ensure that the field's name does not shadow an existing attribute of the model.
+            """
+            for base in bases:
+                if getattr(base, field_name, None):
+                    raise NameError(f"Variable name '{field_name}' shadows a '{base.__name__}' attribute.")
+
+        # extract and build fields
         class_vars = set()
         if (namespace.get('__module__'), namespace.get('__qualname__')) != \
                 ('larray.core.constrained', 'ConstrainedSession'):
-            annotations = resolve_annotations(namespace.get('__annotations__', {}), namespace.get('__module__', None))
-            untouched_types = UNTOUCHED_TYPES
+
             # annotation only fields need to come first in fields
+            annotations = resolve_annotations(namespace.get('__annotations__', {}), namespace.get('__module__', None))
             for ann_name, ann_type in annotations.items():
                 if is_classvar(ann_type):
                     class_vars.add(ann_name)
-                elif is_valid_field(ann_name):
+                elif not ann_name.startswith('_'):
                     validate_field_name(bases, ann_name)
                     value = namespace.get(ann_name, Undefined)
+                    cls = getattr(ann_type, '__origin__', None)
                     if (
-                        isinstance(value, untouched_types)
-                        and ann_type != PyObject
-                        and not lenient_issubclass(getattr(ann_type, '__origin__', None), Type)
+                            isinstance(value, untouched_types)
+                            # and ann_type != PyObject    (from pydantic.types import PyObject)
+                            and not (isinstance(cls, type) and issubclass(cls, Type))
                     ):
                         continue
                     fields[ann_name] = ModelField.infer(
@@ -210,10 +219,12 @@ def inherit_validators(base_validators: Dict[str, List[Validator]],
 
             for var_name, value in namespace.items():
                 if (
-                    var_name not in annotations
-                    and is_valid_field(var_name)
-                    and not isinstance(value, untouched_types)
-                    and var_name not in class_vars
+                        # namespace.items() contains annotated fields with default values
+                        var_name not in annotations
+                        and not var_name.startswith('_')
+                        and not isinstance(value, untouched_types)
+                        # avoid to update a field if it was redeclared (by mistake)
+                        and var_name not in class_vars
                 ):
                     validate_field_name(bases, var_name)
                     inferred = ModelField.infer(
@@ -269,10 +280,6 @@ class ConstrainedSession(Session, metaclass=ModelMetaclass):
         * 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.
-        * allow_extra: bool, optional
-            Whether to allow or forbid extra variables during session initialization (and after). Defaults to True.
-        * allow_mutation: bool, optional
-            Whether or not variables can be modified after initialization. Defaults to True.
 
     Warnings
     --------
@@ -283,7 +290,7 @@ class ConstrainedSession(Session, metaclass=ModelMetaclass):
 
     See Also
     --------
-    Session
+    Session, Parameters
 
     Examples
     --------
@@ -308,7 +315,7 @@ class ConstrainedSession(Session, metaclass=ModelMetaclass):
     ...     # --- 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[18:] >> 'adults'
+    ...     target_age: Group = 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
@@ -397,6 +404,7 @@ class ConstrainedSession(Session, 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 population ... done
@@ -409,18 +417,16 @@ class ConstrainedSession(Session, metaclass=ModelMetaclass):
         __validators__: Dict[str, List[Validator]] = {}
         __config__: Type[BaseConfig] = BaseConfig
 
+    __allow_extra__ = True
+    __allow_mutation__ = True
+
     # Warning: order of fields is not preserved.
     # As of v1.0 of pydantic all fields with annotations (whether annotation-only or with a default value)
     # will precede all fields without an annotation. Within their respective groups, fields remain in the
     # order they were defined.
     # See https://pydantic-docs.helpmanual.io/usage/models/#field-ordering
-    # Furthermore, among fields with annotations those with default values are put after
-    # Uses something other than `self` the first arg to allow "self" as a settable attribute
     def __init__(self, *args, **kwargs):
         meta = kwargs.pop('meta', Metadata())
-        self.__config__.allow_extra = kwargs.pop('allow_extra', True)
-        self.__config__.allow_mutation = kwargs.pop('allow_mutation', True)
-
         Session.__init__(self, meta=meta)
 
         # create an intermediate Session object to not call the __setattr__
@@ -449,11 +455,12 @@ def __init__(self, *args, **kwargs):
 
     # code of the method below has been partly borrowed from pydantic.BaseModel.__setattr__()
     def _check_key_value(self, name: str, value: Any, skip_allow_mutation: bool, skip_validation: bool) -> Any:
-        if not self.__config__.allow_extra and name not in self.__fields__:
+        cls = self.__class__
+        if not cls.__allow_extra__ and name not in self.__fields__:
             raise ValueError(f"Variable '{name}' is not declared in '{self.__class__.__name__}'. "
                              f"Adding undeclared variables is forbidden. "
                              f"List of declared variables is: {list(self.__fields__.keys())}.")
-        if not skip_allow_mutation and not self.__config__.allow_mutation:
+        if not skip_allow_mutation and not cls.__allow_mutation__:
             raise TypeError(f"Cannot change the value of the variable '{name}' since '{self.__class__.__name__}' "
                             f"is immutable and does not support item assignment")
         known_field = self.__fields__.get(name, None)
@@ -492,3 +499,62 @@ def dict(self, exclude: Set[str] = None):
             if name in d:
                 del d[name]
         return d
+
+
+class Parameters(ConstrainedSession):
+    """
+    Same as py:class:`ConstrainedSession` but:
+
+        * declared variables cannot be modified after initialization
+        * adding undeclared variables after initialization is forbidden.
+
+    Parameters
+    ----------
+    *args : str or dict of {str: object} or iterable of tuples (str, object)
+        Path to the file containing the session to load or
+        list/tuple/dictionary containing couples (name, object).
+    **kwargs : dict of {str: object}
+
+        * Objects to add written as name=object
+        * 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.
+
+    See Also
+    --------
+    ConstrainedSession
+
+    Examples
+    --------
+
+    Content of file 'parameters.py'
+
+    >>> from larray import *
+    >>> class ModelParameters(Parameters):
+    ...     # --- declare variables with fixed values ---
+    ...     # The given values can never be changed
+    ...     FIRST_YEAR = 2020
+    ...     LAST_YEAR = 2030
+    ...     AGE = Axis('age=0..10')
+    ...     GENDER = Axis('gender=male,female')
+    ...     TIME = Axis(f'time={FIRST_YEAR}..{LAST_YEAR}')
+    ...     # --- declare variables with defined types ---
+    ...     # Their values must be defined at initialized and will be frozen after.
+    ...     variant_name: str
+
+    Content of file 'model.py'
+
+    >>> # instantiation --> create an instance of the ModelVariables class
+    >>> # all variables declared without value must be set
+    >>> P = ModelParameters(variant_name='variant_1')
+    >>> # once an instance is create, its variables can be accessed but not modified
+    >>> P.variant_name
+    'variant_1'
+    >>> P.variant_name = 'new_variant'      # doctest: +NORMALIZE_WHITESPACE
+    Traceback (most recent call last):
+        ...
+    TypeError: Cannot change the value of the variable 'variant_name' since 'ModelParameters'
+    is immutable and does not support item assignment
+    """
+    __allow_extra__ = False
+    __allow_mutation__ = False