Conn auth

RELEASE_NOTES.md

@@ -1,6 +1,7 @@
 
 # Next Release
 
+- [#243](https://github.com/IAMconsortium/pyam/pull/243) Update `pyam.iiasa.Connection` to support all public and private database connections. DEPRECATED: the argument 'iamc15' has been deprecated in favor of names as queryable directly from the REST API.
 - [#236](https://github.com/IAMconsortium/pyam/pull/236) Add `swap_time_for_year` method and confirm datetime column is compatible with pyam features
 
 # Release v0.2.0

doc/source/tutorials/iiasa_dbs.ipynb

@@ -28,15 +28,14 @@
     }
    ],
    "source": [
-    "import pyam\n",
-    "from pyam.iiasa import valid_connection_names"
+    "import pyam"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "There are currently not many available data sources, but more will be added with time"
+    "Accessing an explorer is done via a `Connection` object. By default, all public explorers can be connected to. "
    ]
   },
   {
@@ -47,7 +46,7 @@
     {
      "data": {
       "text/plain": [
-       "['iamc15']"
+       "['IXSE_SETNAV', 'IXSE_SR15', 'IXSE_SR15_QA', 'IXSE_TEST_PUBLIC']"
       ]
      },
      "execution_count": 2,
@@ -56,21 +55,45 @@
     }
    ],
    "source": [
-    "valid_connection_names()"
+    "conn = pyam.iiasa.Connection()\n",
+    "conn.valid_connections"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In this example, we will be pulling data from the Special Report on 1.5C explorer. This can be done in a number of ways, for example\n",
+    "If you have additional credentials, you can supply them as well via the `creds` key-word argument:\n",
     "\n",
     "```\n",
-    "pyam.read_iiasa('iamc15')\n",
-    "pyam.read_iiasa_iamc15()\n",
+    "pyam.iiasa.Connection(creds=(<username>, <password>))\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this example, we will be pulling data from the Special Report on 1.5C explorer. This can be done either via the constructor:\n",
+    "\n",
+    "```\n",
+    "pyam.iiasa.Connection('IXSE_SR15')\n",
     "```\n",
     "\n",
-    "However, this would pull all available data. It is also possible to query specific subsets of data in a manner similar to `pyam.IamDataFrame.filter()`."
+    "or, if you want to query multiple databases, via the explicit `connect()` method:\n",
+    "\n",
+    "```\n",
+    "conn = pyam.iiasa.Connection()\n",
+    "conn.connect('IXSE_SR15')\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We also provide some convenience functions to shorten the amount of code you have to write. Under the hood, `read_iiasa()` is just opening an connection to a database and making a query on that data.\n",
+    "In this tutorial, we will query specific subsets of data in a manner similar to `pyam.IamDataFrame.filter()`."
    ]
   },
   {
@@ -82,14 +105,13 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "INFO:root:You are connected to the iamc15 scenario explorer. Please cite as:\n",
-      "\n",
-      "D. Huppmann, E. Kriegler, V. Krey, K. Riahi, J. Rogelj, S.K. Rose, J. Weyant, et al., IAMC 1.5C Scenario Explorer and Data hosted by IIASA. IIASA & IAMC, 2018. doi: 10.22022/SR15/08-2018.15429, url: data.ene.iiasa.ac.at/iamc-1.5c-explorer\n"
+      "INFO:root:You are connected to the IXSE_SR15 scenario explorer hosted by IIASA. If you use this data in any published format, please cite the data as provided in the explorer guidelines: https://data.ene.iiasa.ac.at/iamc-1.5c-explorer/#/about.\n"
      ]
     }
    ],
    "source": [
-    "df = pyam.read_iiasa_iamc15(\n",
+    "df = pyam.read_iiasa(\n",
+    "    'IXSE_SR15',\n",
     "    model='MESSAGEix*', \n",
     "    variable=['Emissions|CO2', 'Primary Energy|Coal'], \n",
     "    region='World',\n",
@@ -183,14 +205,12 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "INFO:root:You are connected to the iamc15 scenario explorer. Please cite as:\n",
-      "\n",
-      "D. Huppmann, E. Kriegler, V. Krey, K. Riahi, J. Rogelj, S.K. Rose, J. Weyant, et al., IAMC 1.5C Scenario Explorer and Data hosted by IIASA. IIASA & IAMC, 2018. doi: 10.22022/SR15/08-2018.15429, url: data.ene.iiasa.ac.at/iamc-1.5c-explorer\n"
+      "INFO:root:You are connected to the IXSE_SR15 scenario explorer hosted by IIASA. If you use this data in any published format, please cite the data as provided in the explorer guidelines: https://data.ene.iiasa.ac.at/iamc-1.5c-explorer/#/about.\n"
      ]
     }
    ],
    "source": [
-    "conn = pyam.iiasa.Connection('iamc15')"
+    "conn = pyam.iiasa.Connection('IXSE_SR15')"
    ]
   },
   {
@@ -283,11 +303,11 @@
     {
      "data": {
       "text/plain": [
-       "0          World\n",
-       "1         R5ASIA\n",
-       "2          R5LAM\n",
-       "3          R5MAF\n",
-       "4    R5OECD90+EU\n",
+       "0     World\n",
+       "1    R5ROWO\n",
+       "2    R5ASIA\n",
+       "3     R5LAM\n",
+       "4     R5MAF\n",
        "Name: region, dtype: object"
       ]
      },
@@ -509,7 +529,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.2"
+   "version": "3.7.3"
   }
  },
  "nbformat": 4,

pyam/__init__.py

@@ -5,7 +5,7 @@
 from pyam.read_ixmp import *
 from pyam.logger import *
 from pyam.run_control import *
-from pyam.iiasa import read_iiasa, read_iiasa_iamc15  # noqa: F401
+from pyam.iiasa import read_iiasa  # noqa: F401
 
 # in Jupyter notebooks: disable autoscroll, activate warnings
 try: