Add a pyam.iiasa.platforms() function

RELEASE_NOTES.md

@@ -1,5 +1,6 @@
 # Next release
 
+- [#829](https://github.com/IAMconsortium/pyam/pull/829) Add a `pyam.iiasa.list_platforms()` function
 - [#826](https://github.com/IAMconsortium/pyam/pull/826) Add `read_ixmp4()` function and extend integration test
 - [#825](https://github.com/IAMconsortium/pyam/pull/825) Add support for Python 3.12
 - [#824](https://github.com/IAMconsortium/pyam/pull/824) Update ixmp4 requirement to >=0.7.1

docs/api/iiasa.rst

@@ -38,10 +38,15 @@ You will be prompted to enter your password.
 *Scenario Apps* instances
 -------------------------
 
-Coming soon...
+The *Scenario Apps* use the |ixmp4| package as a database backend.
+You can list all available ixmp4 platforms hosted by IIASA using the following:
 
-*Scenario Explorer* instances
------------------------------
+.. autofunction:: list_platforms
+   :noindex:
+
+
+*Scenario Explorer* instances (legacy service)
+----------------------------------------------
 
 The *Scenario Explorer* infrastructure developed by the Scenario Services and Scientific
 Software team was developed and used for projects from 2018 until 2023.

pyam/iiasa.py

@@ -12,13 +12,14 @@
 import pandas as pd
 import requests
 import yaml
+from ixmp4.cli import utils
 from ixmp4.conf import settings
 from ixmp4.conf.auth import ManagerAuth
 from requests.auth import AuthBase
 
 from pyam.core import IamDataFrame
 from pyam.logging import deprecation_warning
-from pyam.str import is_str
+from pyam.str import is_str, shorten
 from pyam.utils import (
     IAMC_IDX,
     META_IDX,
@@ -35,13 +36,32 @@
 You are connected to the {} scenario explorer hosted by IIASA.
  If you use this data in any published format, please cite the
  data as provided in the explorer guidelines: {}
-""".replace("\n", "")
+""".replace(
+    "\n", ""
+)
 IXMP4_LOGIN = "Please run `ixmp4 login <username>` in a console"
 
 # path to local configuration settings
 DEFAULT_IIASA_CREDS = Path("~").expanduser() / ".local" / "pyam" / "iiasa.yaml"
 
 
+def list_platforms():
+    """Print all available ixmp4 platforms hosted by IIASA"""
+
+    platforms = ixmp4.conf.settings.manager.list_platforms()
+    utils.echo("IIASA platform".ljust(20) + "Access".ljust(10) + "Notice\n")
+
+    for p in platforms:
+        utils.important(shorten(p.name, 20), nl=False)
+        utils.echo(str(p.accessibility.value.lower()).ljust(10), nl=False)
+
+        if p.notice is not None:
+            utils.echo(shorten(p.notice, 55), nl=False)
+        utils.echo()
+
+    utils.info("\n" + str(len(platforms)) + " total \n")
+
+
 def set_config(user, password, file=None):
     raise DeprecationWarning(f"This method is deprecated. {IXMP4_LOGIN}.")
 
@@ -197,6 +217,10 @@
     @lru_cache()
     def valid_connections(self):
         """Return available resources (database API connections)"""
+        logger.warning(
+            "IIASA is migrating to a database infrastructure using the ixmp4 package."
+            "Use `pyam.iiasa.list_platforms()` to list available ixmp4 databases."
+        )
         return list(self._connection_map.keys())
 
     def connect(self, name):

pyam/str.py

@@ -65,18 +65,21 @@
         # test = lambda x: level == x if x is not None else False
         def test(x):
             return level == x if x is not None else False
+
     elif level[-1] == "-":
         level = int(level[:-1])
 
         # test = lambda x: level >= x if x is not None else False
         def test(x):
             return level >= x if x is not None else False
+
     elif level[-1] == "+":
         level = int(level[:-1])
 
         # test = lambda x: level <= x if x is not None else False
         def test(x):
             return level <= x if x is not None else False
+
     else:
         raise ValueError("Unknown level type: `{}`".format(level))
 
@@ -141,3 +144,10 @@
 def is_str(x):
     """Returns True if x is a string"""
     return isinstance(x, six.string_types)
+
+
+def shorten(value: str, length: int):
+    """Shorten a string to a given length adding `...`"""
+    if len(value) > length - 4:
+        value = value[: length - 4] + "..."
+    return value.ljust(length)