logging best practice (#724)

* config: set logging style only if the config value logging.climada_style says so

* changelog entry added

* fix climada.conf: set logging.climada_style in package config, not test
changelog: add PR number

* doc install: make logging section more general

* fix typos

* config: change logging.climada_style -> logging.managed

* changelog: new config name outdated

Author: emanuel-schmid

CHANGELOG.md

@@ -41,6 +41,7 @@ Removed:
 - `Exposures.affected_total_value` now takes a hazard intensity threshold as argument. Affected values are only those for which at least one event exceeds the threshold. (previously, all exposures points with an assigned centroid were considered affected). By default the centroids are reassigned. [#702](https://github.com/CLIMADA-project/climada_python/pull/702) [#730](https://github.com/CLIMADA-project/climada_python/pull/730)
 - Add option to pass region ID to `LitPop.from_shape` [#720](https://github.com/CLIMADA-project/climada_python/pull/720)
 - Slightly improved performance on `LitPop`-internal computations [#720](https://github.com/CLIMADA-project/climada_python/pull/720)
+- Users can opt-out of the climada specific logging definitions and freely configure logging to their will, by setting the config value `logging.managed` to `false`. [#724](https://github.com/CLIMADA-project/climada_python/pull/724)
 - Add option to read additional variables from IBTrACS when using `TCTracks.from_ibtracs_netcdf` [#728](https://github.com/CLIMADA-project/climada_python/pull/728)
 
 ### Fixed

climada/conf/climada.conf

@@ -57,6 +57,9 @@
         }
     },
     "log_level": "WARNING",
+    "logging": {
+        "managed": true
+    },
     "max_matrix_size": 1000000000,
     "data_api": {
         "url": "https://climada.ethz.ch/data-api/v2/",

climada/util/config.py

@@ -30,15 +30,6 @@
 from pathlib import Path
 
 
-LOGGER = logging.getLogger('climada')
-LOGGER.propagate = False
-FORMATTER = logging.Formatter(
-    "%(asctime)s - %(name)s - %(levelname)s - %(message)s")
-CONSOLE = logging.StreamHandler(stream=sys.stdout)
-CONSOLE.setFormatter(FORMATTER)
-LOGGER.addHandler(CONSOLE)
-
-
 class Config():
     """Convenience Class. A Config object is a slow JSON object like nested dictonary who's values
     can be accessed by their names right away. E.g.: `a.b.c.str()` instead of `a['b']['c']`
@@ -360,6 +351,19 @@ def _fetch_conf(directories, config_name):
     Path(Path.home(), '.config'),  # ~/.config directory
     Path.cwd(),  # current working directory
 ]
+
 CONFIG = Config.from_dict(_fetch_conf(CONFIG_DIRS, CONFIG_NAME))
 Config.SOURCE_DIR = SOURCE_DIR
-LOGGER.setLevel(getattr(logging, CONFIG.log_level.str()))
+
+
+# set climada style logging
+if CONFIG.logging.managed.bool():
+    LOGGER = logging.getLogger('climada')
+    LOGGER.propagate = False
+    FORMATTER = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    CONSOLE = logging.StreamHandler(stream=sys.stdout)
+    CONSOLE.setFormatter(FORMATTER)
+    LOGGER.addHandler(CONSOLE)
+
+    LOGGER.setLevel(getattr(logging, CONFIG.log_level.str()))

doc/guide/install.rst

@@ -452,35 +452,43 @@ After **each** of the following steps, check if the problem is solved, and only
 #. Still no good?
    Please raise an `issue on GitHub <https://github.com/CLIMADA-project/climada_python/issues>`_ to get help.
 
-Changing the Logging Level
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Logging Configuration
+^^^^^^^^^^^^^^^^^^^^^
 
-By default the logging level is set to ``INFO``, which is quite verbose.
-You can change this setting in multiple ways:
+Climada makes use of the standard `logging <https://docs.python.org/3/howto/logging.html>`_ package.
+By default, the "climada"-``Logger`` is detached from ``logging.root``, logging to `stdout` with
+the level set to ``WARNING``.
+
+If you prefer another logging configuration, e.g., for using Climada embedded in another application,
+you can opt out of the default pre-configuration by setting the config value for
+``logging.climada_style`` to ``false`` in the :doc:`configuration file <Guide_Configuration>`
+``climada.conf``.
+
+Changing the logging level can be done in multiple ways:
 
 * Adjust the :doc:`configuration file <Guide_Configuration>` ``climada.conf`` by setting a the value of the ``global.log_level`` property.
+  This only has an effect if the ``logging.climada_style`` is set to ``true`` though.
 
 * Set a global logging level in your Python script:
 
   .. code-block:: python
 
-     from climada.util.config import LOGGER
-     from logging import WARNING
-     LOGGER.setLevel(WARNING)
+     import logging
+     logging.getLogger('climada').setLevel(logging.ERROR)  # to silence all warnings
 
 * Set a local logging level in a context manager:
 
   .. code-block:: python
 
      from climada.util import log_level
-     with log_level(level="WARNING"):
-         # This code only emits log levels 'WARNING' or higher
+     with log_level(level="INFO"):
+         # This also emits all info log messages
          foo()
 
      # Default logging level again
      bar()
 
-All of these approaches can also be combined.
+All three approaches can also be combined.
 
 `Mamba <https://mamba.readthedocs.io/en/latest/>`_ Instead of Anaconda
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^