Meta support for model/scenario levels

RELEASE_NOTES.rst

@@ -4,6 +4,18 @@ Next release
 All changes
 -----------
 
+- :pull:`353`: Add meta functionality.
+
+  - :meth:`Platform.add_model` using :meth:`.Backend.add_model`
+  - :meth:`Platform.add_scenario` using :meth:`.Backend.add_scenario`
+  - :meth:`Platform.models` using :meth:`.Backend.models`
+  - :meth:`Platform.scenarios` using :meth:`.Backend.scenarios`
+  - :meth:`Platform.get_meta` using :meth:`.Backend.get_meta`
+  - :meth:`Platform.set_meta` using :meth:`.Backend.set_meta`
+  - :meth:`Platform.remove_meta` using :meth:`.Backend.remove_meta`
+  - :meth:`Scenario.remove_meta` using :meth:`.Backend.remove_scenario_meta`
+  - deprecate :meth:`Scenario.delete_meta`
+
 - :pull:`349`: Avoid modifying indexers dictionary in :meth:`.AttrSeries.sel`.
 - :pull:`343`: Add region/unit parameters to :meth:`.Platform.export_timeseries_data`.
 - :pull:`347`: Preserve dtypes of index columns in :func:`.data_for_quantity`.

doc/README.rst

@@ -28,7 +28,8 @@ There are a number of guides out there, e.g. on docutils_.
 Building the docs locally
 -------------------------
 
-Install the dependencies, above.
+Install the dependencies, above. Repeat the installation steps to be able to
+refer to code that was changed since the initial installation.
 
 From the command line, run::
 

doc/source/api-backend.rst

@@ -93,17 +93,24 @@ Backend API
    .. autosummary::
       :nosignatures:
 
+      add_model
+      add_scenario
       close_db
       get_auth
       get_doc
       get_log_level
+      get_meta
       get_nodes
       get_scenarios
       get_units
+      models
       open_db
       read_file
+      remove_meta
+      scenarios
       set_doc
       set_log_level
+      set_meta
       set_node
       set_unit
       write_file
@@ -142,15 +149,16 @@ Backend API
 
       clone
       delete_item
-      get_meta
+      get_scenario_meta
       has_solution
       init_item
       item_delete_elements
       item_get_elements
       item_set_elements
       item_index
       list_items
-      set_meta
+      remove_scenario_meta
+      set_scenario_meta
 
    Methods related to :class:`message_ix.Scenario`:
 

doc/source/api.rst

@@ -29,11 +29,24 @@ Platform
       set_log_level
       units
 
-   The methods
-   :meth:`~.base.Backend.open_db`,
-   :meth:`~.base.Backend.close_db`,
-   :meth:`~.base.Backend.get_doc`, and
-   :meth:`~.base.Backend.set_doc` may also be called via Platform.
+   The following backend methods are available via Platform too:
+
+   .. autosummary::
+      backend.base.Backend.add_model
+      backend.base.Backend.add_scenario
+      backend.base.Backend.close_db
+      backend.base.Backend.get_doc
+      backend.base.Backend.get_meta
+      backend.base.Backend.models
+      backend.base.Backend.open_db
+      backend.base.Backend.remove_meta
+      backend.base.Backend.scenarios
+      backend.base.Backend.set_doc
+      backend.base.Backend.set_meta
+
+   These methods can be called like normal Platform methods, e.g.::
+
+     $ platform_instance.close_db()
 
 
 TimeSeries

ixmp/backend/base.py

@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
 from copy import copy
+from typing import Generator
 import json
 
 from ixmp.core import TimeSeries, Scenario
@@ -53,6 +54,42 @@ def get_auth(self, user, models, kind):
         """
         return {model: True for model in models}
 
+    @abstractmethod
+    def add_model(self, name: str):
+        """ Add (register) new model name.
+
+        Parameters
+        ----------
+        user : str, new model name
+        """
+
+    @abstractmethod
+    def add_scenario(self, name: str):
+        """ Add (register) new scenario name.
+
+        Parameters
+        ----------
+        user : str, new scenario name
+        """
+
+    @abstractmethod
+    def models(self) -> Generator[str, None, None]:
+        """ List existing model names.
+
+        Returns
+        -------
+        list of str
+        """
+
+    @abstractmethod
+    def scenarios(self) -> Generator[str, None, None]:
+        """ List existing scenario names.
+
+        Returns
+        -------
+        list of str
+        """
+
     @abstractmethod
     def get_nodes(self):
         """Iterate over all nodes stored on the Platform.
@@ -888,31 +925,110 @@ def item_delete_elements(self, s: Scenario, type, name, keys):
         """
 
     @abstractmethod
-    def get_meta(self, s: Scenario):
-        """Return all meta.
+    def get_meta(self, model: str, scenario: str, version: int, strict: bool
+                 ) -> dict:
+        """Retrieve meta.
+
+        Parameters
+        ----------
+        model : str, optional
+            filter meta by a model
+        scenario : str, optional
+            filter meta by a scenario
+        version : int or str, optional
+            retrieve meta of a specific model/scenario run version
+        strict : bool, optional
+            only retrieve indicators from the requested model-scenario-version
+            level
 
         Returns
         -------
         dict (str -> any)
-            Mapping from meta keys to values.
+            Mapping from meta category keys to values.
 
-        See also
-        --------
-        s_get_meta
+        Raises
+        ------
+        ValueError
+            On unsupported model-scenario-version combinations.
+            Supported combinations are: (model), (scenario), (model, scenario),
+            (model, scenario, version)
+        """
+
+    @abstractmethod
+    def set_meta(self, meta: dict, model: str, scenario: str, version: int):
+        """Set meta categories.
+
+        Parameters
+        ----------
+        meta : dict, containing meta key/value category pairs
+        model : str, optional
+            model name that meta should be attached to
+        scenario : str, optional
+            scenario name that meta should be attached to
+        version : int, optional
+            run version that meta should be attached to
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            On unsupported model-scenario-version combinations.
+            Supported combinations are: (model), (scenario), (model, scenario),
+            (model, scenario, version)
+        """
+
+    @abstractmethod
+    def remove_meta(self, categories: list, model: str, scenario: str,
+                    version: int):
+        """Remove meta categories.
+
+        Parameters
+        ----------
+        categories : list of str, meta-category keys to remove
+        model : str, optional
+            only remove meta of a specific model
+        scenario : str, optional
+            only remove meta of a specific scenario
+        version : int, optional
+            only remove meta of a specific model/scenario run version
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            On unsupported model-scenario-version combinations.
+            Supported combinations are: (model), (scenario), (model, scenario),
+            (model, scenario, version)
+        """
+
+    @abstractmethod
+    def get_scenario_meta(self, s: Scenario):
+        """Return all scenario meta.
+
+        Returns
+        -------
+        dict (str -> any)
+            Mapping from meta keys to values.
         """
 
     @abstractmethod
-    def set_meta(self, s: Scenario, name_or_dict, value=None):
-        """Set single or multiple meta entries.
+    def set_scenario_meta(self, s: Scenario, name_or_dict, value=None):
+        """Set single or multiple scenario meta entries.
 
         Parameters
         ----------
         name_or_dict : str or dict
             If the argument is dict, it used as a mapping of meta
             categories (names) to values. Otherwise, use the argument
-            as the meta attribute name.
+            as the meta category name.
         value : str or number or bool, optional
-            Meta attribute value.
+            Meta category value.
 
         Returns
         -------
@@ -925,8 +1041,8 @@ def set_meta(self, s: Scenario, name_or_dict, value=None):
         """
 
     @abstractmethod
-    def delete_meta(self, s, name):
-        """Remove single or multiple meta entries.
+    def remove_scenario_meta(self, s, name):
+        """Remove single or multiple scenario meta entries.
 
         Parameters
         ----------