diff --git a/doc/source/releases/relnotes_v0_31_1.rst b/doc/source/releases/relnotes_v0_31_1.rst new file mode 100644 index 0000000..f82db83 --- /dev/null +++ b/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 ` + * :attr:`UserSpace.info ` + * :attr:`ItemSpace.info ` + * :attr:`DynamicSpace.info ` + * :attr:`Cells.info ` + + This is an experimental feature. Its output format and behavior may + change in future releases without notice. diff --git a/doc/source/updates.rst b/doc/source/updates.rst index e8b85e8..4261fb4 100644 --- a/doc/source/updates.rst +++ b/doc/source/updates.rst @@ -12,6 +12,9 @@ Updates Visit Discussions for more frequent updates.

+* *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`. diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst index af5a54e..52a10a3 100644 --- a/doc/source/whatsnew.rst +++ b/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 diff --git a/modelx/core/base.py b/modelx/core/base.py index f402274..6481340 100644 --- a/modelx/core/base.py +++ b/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)