API Client Tutorial: add a paragraph about offline mode (#496)

* API Client Tutorial: add a paragraph about offline mode

* api_client. change the cache_enabled default
de facto (by configuration) to true

climada.conf

@@ -24,8 +24,7 @@
         "test_data": "{test_directory}/util/test/data"
     },
     "data_api": {
-        "supported_exposures_types": ["litpop", "crop_production", "base"],
-        "cache_enabled": true
+        "supported_exposures_types": ["litpop", "crop_production", "base"]
     },
     "log_level": "INFO"
 }

climada/conf/climada.conf

@@ -65,7 +65,7 @@
         "url": "https://climada.ethz.ch/data-api/v1/",
         "chunk_size": 8192,
         "cache_db": "{local_data.system}/.downloads.db",
-        "cache_enabled": false,
+        "cache_enabled": true,
         "cache_dir": "{local_data.system}/.apicache",
         "supported_hazard_types": ["river_flood", "tropical_cyclone", "storm_europe", "relative_cropyield"],
         "supported_exposures_types": ["litpop", "crop_production"]

doc/tutorial/climada_util_api_client.ipynb

@@ -1071,6 +1071,54 @@
     "download_dir, ds_files = client.download_dataset(ds_tc)\n",
     "ds_files[0], ds_files[0].is_file()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "### Offline Mode\n",
+    "\n",
+    "The API Client is silently used in many methods and functions of CLIMADA, including the installation test that is run to see whether the CLIMADA installation was successful.\n",
+    "Most methods of the client send GET requests to the API server assuming the latter is accessible through a working internet connection.\n",
+    "If this is not the case, the functionality of CLIMADA is severely limited if not altogether lost. Often this is an unnecessary restriction, \n",
+    "e.g., when a user wants to access a file through the API Client that is already downloaded and available in the local filesystem.\n",
+    "\n",
+    "In such cases the API Client runs in _offline mode_.\n",
+    "In this mode the client falls back to previous results for the same call in case there is no internet connection or the server is not accessible.\n",
+    "\n",
+    "To turn this feature off and make sure that all results are current and up to date - at the cost of failing when there is no internet connection - one has to disable tha _cache_.\n",
+    "This can be done programmatically, by initializing the API Client with the optional argument `cache_enabled`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client = Client(cache_enabled=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Or it can be done through configuration. Edit the `climada.conf` file in the working directory or in ~/climada/ and change the \"cache_enabled\" value, like this:\n",
+    "\n",
+    "```javascript\n",
+    "...\n",
+    "    \"data_api\": {\n",
+    "        ...\n",
+    "        \"cache_enabled\": false\n",
+    "    },\n",
+    "...\n",
+    "```\n",
+    "\n",
+    "While `cache_enabled` is `true` (default), every result from the server is stored as a json file in ~/climada/data/.apicache/ by a unique name derived from the method and arguments of the call.\n",
+    "If the very same call is made again later, at a time where the server is not accessible, the client just comes back to the cached result from the previous call."
+   ]
   }
  ],
  "metadata": {