DOC: Document for the next release

doc/source/images/relnotes/v0_10_0/sample_ref.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2020-09-16T14:08:04.734Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/13.6.2 Chrome/83.0.4103.122 Electron/9.2.0 Safari/537.36" etag="Ah_oJcVQ9AUa53Hi2hlB" version="13.6.2" type="device"><diagram id="m_EPO4i9GyNIxP_G-OGp" name="Page-1">7VzbcqM4EP0aP+4Ukrg+zuQyU1u7W1OVVO3MIzGyTQ1GLkIm9n794iAMdMc2YCNk4qcgIdri6HTT6gOZsJvl+mvirxZ/i4BHE2oE6wm7nVBKDNfN/mx7NnmPZ8uOeRIGclDZ8RD+x4srZe9LGPDn2sBUiCgNV/XOqYhjPk1rfX6SiNf6sJmI6r+68uccdTxM/Qj3/hsG6SLvdalT9n/j4XxR/DKxvfzM0i8Gyzt5XviBeK10sbsJu0mESPOj5fqGR1vwClzy6+73nN1NLOFx2uSC2dfwz+iveO4Ej/f3/8SP3zfuwx/Sym8/epE3/FnONt0UECTiJQ741ooxYV9eF2HKH1b+dHv2NVv0rG+RLqOsRbLDWRhFNyISydu1LLC4G5hZ/3OaiF+8csalT8y2szNyBjxJ+XrvrZEdYBnTuFjyNNlkQ+QFzJUYS5LRov1aLpktuxaV1TJlny9JMt9ZLnHMDiSULWClCNYvI4CV2QPDyhCsMyEOAEvaA+tzdzZ9D1h76vKn2ZmApXVgTWdgYE0E7JOfnBXYmTvl03eBfXIt0zLOA6xpEr2AtRGwtxcYCIhN9QoEzkgCATHqwA7OV3ckgYBSzYAt8tkKsghWHgeftylr1nqKxPRXBkXWJXNiQvPmfbj94bdQUQE5gyXZ/JD9b42f28Ynq2jerqsnbzdFax2mPwob2XHlqqxVXrRtFNfk8+YBSpzB4mT3Jl6SKT+AigyPqZ/MeXosn8KLXVlMUqxmwiM/DX/X5/beckpz30WYzXpHHJvVnyC7HKgwkd+TvKqabgND8FGEDOU3jQy9sWt3jycQDqf2hwgXhP5SxMHjIoxrPCOYhO/SrmTaz+q5I7QrqfazyrS+aUcb0m5PjOmBdqYBMkKvI+0s+4ihvmmHtz6XTbst4R7k3EWSLsRcxH50V/aek5hMu3hogq0Kc7rGQ2iINCNmxhR/Uxm22g543j9hZgEHMI3D8yIHx2cH+QzO6yV4J3v1ksZeYmrnJQxG3c5ZA6wM9OQlu3xYay/BZYmrlzT2EkcZ+wnbs9lqy37iAUNGP+xHEz7CfjQvJez3ruzfw34lrKbWhbEaTVhHVhfPt4asFiseYwIH/vNiV356j82kyuXmVRCjymV1VZCm+QxTl8949ce91ZX7lnXEUM/bUdquCtKSbsPSxlUXCimrR4qu1QkoJKiuThSrPzK92y1gHEzvxvvZMQje3tCqAcU7oMsUuqDiTYzBX9GwELSXKXVBoUEDaMepeg8fDcYqe2tA2bEK3xpA266O8UGUb9pY+la364Pat9c1zYePJGSo5zSftSsy6F86OyfxGmuMVBnxoPpNCCyRdZW/saW+qTe21y6Uaha0aSlMYVSEkpx3Lm3Po82oeaoCTgyrnbgHL+inElxoMFdP6eQpln6eAlVwYnROIFC5oCdfgTq4rr5yfV/kFF8ZTgovt1+nqobE6OlVEDzlIy6AZ6bEBa4vg2glh18As/GU9WQ2rkQfYrZiSfyTo2tUb5wBqdvIQt2ckK5OAoVzbKnvjSwu4vfAyrZFu6ME68Tbc7LS1Y+VUL7vXl6Bkoj68gqWQMYg4FuuDGaDfVmN9Y8xCPi2PTSuWPy4TMkOCviOMzCyheGLV+ygWDI8sriEfXuBsQA+qwaPBSYdSSyA8v3wjMXlscuMBVC9Hx7ZdlWXDyLeFxHy+Bvb6t7RheK9XaSUp4r3yFDPKb7Zrhyif6HvjMRjTXeXTF3JG4r3jteReFC7R4b6Jl67iof+xFP76bqnX0yEMqLtdI2J0BBpRs1TpXtHBsOmaiQY30+92sQ1mKufNM8dDP38BAr3TufcAVYJevITKNvr6Se4pnb1k+Z+QpXRHyrgTtfHBNQPHaMf+qMJH6E/mpcS+l+/X9dKsNee1WjCOrLawmXnQ6z+GN+vN05pPHUpDVDi3a7sh0I8MtTzrtTq8wv25iTQaW2pCxy/a8UBSgTnqzhkzfI/u+fDy/+Pz+7+Bw==</diagram></mxfile>

doc/source/reference/space/userspace.rst

@@ -80,6 +80,17 @@ Child Cells operations
   ~UserSpace.new_cells_from_pandas
   ~UserSpace.import_funcs
 
+Reference operations
+--------------------
+
+.. autosummary::
+  :toctree: generated/
+  :template: mxbase.rst
+
+  ~UserSpace.set_ref
+  ~UserSpace.absref
+  ~UserSpace.relref
+
 
 ItemSpace operations
 ---------------------

doc/source/releases/relnotes_v0_10_0.rst

@@ -0,0 +1,115 @@
+
+===============================
+modelx v0.10.0 (17 Sep 2020)
+===============================
+
+
+This release introduces the following enhancements and changes.
+
+Enhancements
+============
+
+.. rubric:: Introduction of reference mode
+
+References now have *reference mode*, an attribute to control how
+the values of their derived References are determined when the values
+are core modelx objects, such as Spaces or Cells.
+The *reference mode* attribute can be set to either "absolute", "relative" or
+"auto". To specify a reference mode when setting a Reference, following
+methods are introduced.
+
+.. py:currentmodule:: modelx.core.space
+
+* :meth:`UserSpace.absref` for setting *absolute* References
+* :meth:`UserSpace.relref` for setting *relative* References
+* :meth:`UserSpace.set_ref` for setting a Reference in a specified reference mode
+
+When a Reference is in the *absolute* mode, its derived Reference is bound
+to the same object as the base Reference.
+
+When a Reference is in the *relative* mode, its derived Reference is bound
+to an object whose relative position to the derived Reference is
+consistent to the relative position of the object referenced by the base
+Reference to the base Reference. When no such value exists, an Error
+is raised.
+
+When a Reference is in the *auto* mode, its derived Reference is bound
+relatively when possible, or absolutely when not possible.
+
+**Illustration**
+
+In the diagram below, ``A`` is a UserSpace,
+``B`` is a child UserSpace of ``A``, and ``foo`` is a child Cells of ``B``.
+
+The next code defines ``bar`` in ``B`` as an *absolute* Reference to ``foo``::
+
+    >>> B.absref(bar=B.foo)
+
+.. figure:: /images/relnotes/v0_10_0/sample1_base.png
+
+When a new UserSpace ``D`` is derived from ``B``,
+the derived Reference ``bar`` in ``D`` is bound to ``foo`` in ``B``::
+
+    >>> D.bar
+    <Cells foo(x) in Model1.B>
+
+.. figure:: /images/relnotes/v0_10_0/sample1_absref.png
+
+Alternatively, ``bar`` in ``B`` can be defined as an *relative* Reference
+as below::
+
+    >>> B.relref(bar=B.foo)
+
+In this case, the derived Reference ``bar`` in ``D``
+is bound to ``foo`` in ``D``::
+
+    >>> D.bar
+    <Cells foo(x) in Model1.D>
+
+.. figure:: /images/relnotes/v0_10_0/sample1_relref.png
+
+Alternatively, ``bar`` in ``B`` can be defined as an *auto* Reference
+by the assignment operation::
+
+    >>> B.bar = B.foo
+
+Since relative referencing is possible, ``D.bar`` is bound to ``D.foo``::
+
+    >>> D.bar
+    <Cells foo(x) in Model1.D>
+
+In the next example, ``B.bar`` can be bound to ``A``
+only in *absolute* mode or *auto* mode. Trying to bound ``B.bar``
+to ``A`` in *relative* mode will raise an Error, because
+``A`` is out of the tree originated from ``B`` and no corresponding
+object exists for ``D.bar``::
+
+    >>> B.absref(bar=B.foo)     # in absolute mode, or
+
+    >>> B.bar = B.foo           # in auto mode
+
+.. figure:: /images/relnotes/v0_10_0/sample2_base.png
+
+In either mode, ``D.bar`` is bound to ``A``::
+
+    >>> D.bar
+    <UserSpace A in Model1>
+
+.. figure:: /images/relnotes/v0_10_0/sample2_absref.png
+
+
+Backward Incompatible Changes
+=============================
+
+Prior to this version, all References are in the *absolute* mode.
+Now, the Reference assignment operation assigns modelx objects in *auto* mode,
+which may result in some references being bound to unintended objects
+when relative referencing is possible. These References now need to be
+set explicitly as *absolute* References either by :meth:`UserSpace.absref`
+or :meth:`UserSpace.set_ref`.
+
+Bug Fixes
+=========
+
+* Bug where Excel files referenced by :class:`~modelx.io.excelio.ExcelRange`
+  were not saved when they were not modified.

doc/source/updates.rst

@@ -4,6 +4,10 @@ Updates
 
 .. Latest Updates Begin
 
+* *17 Sep 2020:*
+  modelx v0.10.0 is released. see
+  :doc:`releases/relnotes_v0_10_0` release notes for details.
+
 * *9 Aug 2020:*
   modelx v0.9.0 is released. See
   :doc:`releases/relnotes_v0_9_0` release notes for details.

doc/source/whatsnew.rst

@@ -48,6 +48,7 @@ Release Notes - modelx
 .. toctree::
    :maxdepth: 2
 
+   releases/relnotes_v0_10_0
    releases/relnotes_v0_9_0
    releases/relnotes_v0_8_0
    releases/relnotes_v0_7_0

modelx/core/base.py

@@ -432,6 +432,10 @@ def __new__(cls, _impl):
             raise ValueError("Invalid direct constructor call.")
 
     def _get_object(self, name, as_proxy=False):
+        """Get an object from its dotted name
+
+        Used also for retrieving Leaf's attributes by spyder-modelx
+        """
         parts = name.split(".")
 
         try:

modelx/core/space.py

@@ -801,17 +801,98 @@ def __contains__(self, item):
     # Getting and setting attributes
 
     def absref(self, **kwargs):
+        """Set absolute References
 
+        Set References in the *absolute* reference mode by passing a pair
+        of the References' names and values as keyword arguments.
+
+        Setting a Reference by this method is equivalent to
+        calling :meth:`set_ref` by passing "absolute" to ``refmode``.
+
+        Example:
+            ``A`` and ``B`` are UserSpaces and ``foo`` is a Cells in ``B``.
+            The code blow assigns the Cells to References with
+            the same names as the Cells in Space ``A``::
+
+                >>> A.absref(foo=B.foo)
+
+                >>> A.foo
+                <Cells foo(x) in Model1.B>
+
+            By passing multiple keyword assignments, multiple References
+            can be assigned.
+            Below ``bar`` and ``baz`` are Cells in ``B``::
+
+                >>> A.absref(bar=B.bar, baz=B.baz)
+
+                >>> A.bar
+                <Cells bar(x) in Model1.B>
+
+                >>> A.baz
+                <Cells baz(x) in Model1.B>
+
+        See Also:
+            :meth:`set_ref`
+            :meth:`relref`
+
+        """
         for name, value in kwargs.items():
             self.set_ref(name, value, refmode="absolute")
 
     def relref(self, **kwargs):
+        """Set relative References
+
+        Set References in the *relative* reference mode by passing a pair
+        of the References' names and values as keyword arguments.
+
+        Setting a Reference by this method is equivalent to
+        calling :meth:`set_ref` by passing "relative" to ``refmode``.
+
+        Example:
+            ``A`` and ``B`` are UserSpaces and ``foo`` is a Cells in ``B``.
+            The code blow assigns the Cells to References with
+            the same names as the Cells in Space ``A``::
 
+                >>> A.absref(foo=B.foo)
+
+                >>> A.foo
+                <Cells foo(x) in Model1.B>
+
+            By passing multiple keyword assignments, multiple References
+            can be assigned.
+            Below ``bar`` and ``baz`` are Cells in ``B``::
+
+                >>> A.absref(bar=B.bar, baz=B.baz)
+
+                >>> A.bar
+                <Cells bar(x) in Model1.B>
+
+                >>> A.baz
+                <Cells baz(x) in Model1.B>
+
+        See Also:
+            :meth:`set_ref`
+            :meth:`absref`
+
+        """
         for name, value in kwargs.items():
             self.set_ref(name, value, refmode="relative")
 
     def set_ref(self, name, value, refmode):
+        """Set a Reference
 
+        Set a Reference that assigns ``value`` to ``name`` in this Space.
+
+        Args:
+            name: Reference name
+            value: Reference value
+            refmode: "auto", "absolute" or "relative" to indicate
+                reference mode
+
+        See Also:
+            :meth:`relref`
+            :meth:`absref`
+        """
         if hasattr(type(self), name):
             raise AttributeError("cannot set '%s'" % name)
         elif name in self.properties: