DOC: Document info property and add v0.31.1 release notes

doc/source/releases/relnotes_v0_31_1.rst

@@ -0,0 +1,33 @@
+====================================
+modelx v0.31.1 (31 May 2026)
+====================================
+
+This release introduces the following enhancement.
+
+To update modelx to the latest version, use the following command::
+
+    >>> pip install modelx --upgrade
+
+Anaconda users should use the ``conda`` command instead::
+
+    >>> conda update modelx
+
+
+Enhancements
+==============
+
+* The ``info`` property, available on each subclass of
+  :class:`~modelx.core.base.Interface`, returns a lightweight wrapper whose
+  ``repr`` displays a human-readable snapshot of the object -- such as the
+  cells' signature, formula source, cached values and input values for a
+  cells, or the parameters and child item spaces for a space. The property
+  is available on the following classes:
+
+  * :attr:`Model.info <modelx.core.model.Model.info>`
+  * :attr:`UserSpace.info <modelx.core.space.UserSpace.info>`
+  * :attr:`ItemSpace.info <modelx.core.space.ItemSpace.info>`
+  * :attr:`DynamicSpace.info <modelx.core.space.DynamicSpace.info>`
+  * :attr:`Cells.info <modelx.core.cells.Cells.info>`
+
+  This is an experimental feature. Its output format and behavior may
+  change in future releases without notice.

doc/source/updates.rst

@@ -12,6 +12,9 @@ Updates
     Visit <a href="https://github.com/fumitoh/modelx/discussions" target="_blank">Discussions</a>
     for more frequent updates.</p>
 
+* *31 May 2026:*
+  modelx v0.31.1 is released. See :doc:`releases/relnotes_v0_31_1`.
+
 * *17 May 2026:*
   modelx v0.31.0 is released. See :doc:`releases/relnotes_v0_31_0`.
 

doc/source/whatsnew.rst

@@ -37,6 +37,7 @@ Release Notes - modelx
 .. toctree::
    :maxdepth: 1
 
+   releases/relnotes_v0_31_1
    releases/relnotes_v0_31_0
    releases/relnotes_v0_30_1
    releases/relnotes_v0_30_0

modelx/core/base.py

@@ -448,13 +448,33 @@ def foo(x):
     def info(self):
         """An object whose ``repr`` summarizes this Interface.
 
+        .. warning::
+
+           This is an experimental feature. Its output format and
+           behavior may change in future releases without notice.
+
         Returns a lightweight wrapper whose string representation displays
         a human-readable snapshot of this object. The exact fields depend
         on the concrete type:
 
+        * For :class:`~modelx.core.model.Model`: the model's name,
+          the number of top-level spaces and an abbreviated list of their
+          names.
+
+        * For spaces (:class:`~modelx.core.space.UserSpace`,
+          :class:`~modelx.core.space.ItemSpace`,
+          :class:`~modelx.core.space.DynamicSpace`): the space's
+          fully-qualified representation (e.g., ``Model1.Space1[1]``),
+          the list of base spaces' fullnames,
+          :attr:`~modelx.core.space.BaseSpace.parameters` (when defined,
+          shown as a signature string such as ``i, j=0``),
+          the number of :class:`~modelx.core.space.ItemSpace` children,
+          and an abbreviated list of the item-space keys.
+
         * For :class:`~modelx.core.cells.Cells`: the cells' fully-qualified
           representation including its signature
           (e.g., ``Model1.Space1[1].foo(t, i=0)``),
+          whether the cells is derived from a base space,
           :attr:`~modelx.core.cells.Cells.is_cached`,
           :attr:`allow_none`, the source of the
           :attr:`~modelx.core.cells.Cells.formula`,
@@ -463,26 +483,56 @@ def info(self):
           assigned -- the number of input values along with an abbreviated
           listing of input key-value pairs.
 
-        * For spaces: the space's fully-qualified representation
-          (e.g., ``Model1.Space1[1]``),
-          :attr:`~modelx.core.space.BaseSpace.parameters` (when defined,
-          shown as a signature string such as ``i, j=0``),
-          the number of :class:`~modelx.core.space.ItemSpace` children,
-          and an abbreviated list of the item-space keys.
+        Examples:
+            For a :class:`~modelx.core.model.Model`:
+
+            .. code-block:: python
+
+                >>> model.info
+                Model: Model1
+                spaces: 1
+                    ['Space1']
+
+            For a :class:`~modelx.core.space.UserSpace`:
+
+            .. code-block:: python
+
+                >>> model.Space1.info
+                UserSpace: Model1.Space1
+                bases: []
+                parameters: i, j=0
+                itemspaces: 2
+                    [(1, 0), (2, 0)]
+
+            For an :class:`~modelx.core.space.ItemSpace`:
+
+            .. code-block:: python
+
+                >>> model.Space1[1].info
+                ItemSpace: Model1.Space1[1, 0]
+                bases: []
+                itemspaces: 0
+
+            For a :class:`~modelx.core.space.DynamicSpace`, the layout
+            matches :class:`~modelx.core.space.ItemSpace` but the header
+            class name is ``DynamicSpace``.
+
+            For :class:`~modelx.core.cells.Cells`:
 
-        Example:
             .. code-block:: python
 
-                >>> space.foo.info
-                Cells: Model.Space.foo(t)
+                >>> model.Space1[1].foo.info
+                Cells: Model1.Space1[1].foo(t, i=0)
+                is_derived: False
                 is_cached: True
                 allow_none: None
                 formula:
-                    def foo(t):
-                        return t * 2
-                cached values: 2
-                    0: 0
-                    1: 2
+                    def foo(t, i=0):
+                        if t == 0:
+                            return i
+                        return foo(t - 1, i) + 1
+                cached values: 1
+                    (0, 0): 0
         """
         from modelx.core.info import build_info
         return build_info(self)