Merge pull request #279 from primap-community/less-logging-default

changelog/279.enhancement.md

@@ -0,0 +1 @@
+We now skip debug messages in the default logger.

docs/source/usage/index.md

@@ -13,6 +13,7 @@ In this section, we will show the fundamentals of how to work with primap2 data.
 select_and_view
 store_and_load
 add_and_overwrite
+logging
 merge
 skipna
 downscaling

docs/source/usage/logging.md

@@ -0,0 +1,66 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+# Log messages
+
+Many primap2 functions emit log messages, which have an associated severity.
+The severities we use are shown in the table.
+
+| severity | used for                                                                         | default |
+|----------|----------------------------------------------------------------------------------|---------|
+| debug    | useful for understanding what functions do internally                            | ✗       |
+| info     | noteworthy information during normal processing                                  | ✓       |
+| warning  | problems which are not necessarily fatal, but should be acknowledged by the user | ✓       |
+| error    | problems which need to be solved by the user                                     | ✓       |
+
+As noted, by default `debug` messages are not shown, all other messages are shown.
+
+## Changing what is shown
+
+As said, by default `debug` messages are not shown, as you can see here:
+
+```{code-cell} ipython3
+import primap2
+import sys
+
+from loguru import logger
+
+logger.debug("This message will not be shown")
+logger.info("This message will be shown")
+```
+
+To change this, remove the standard logger and add a new logger:
+
+```{code-cell} ipython3
+logger.remove()
+logger.add(sys.stderr, level="DEBUG")
+
+logger.debug("Now you see debug messages")
+logger.info("You still also see info messages")
+```
+
+Instead of showing more, you can also show less:
+
+```{code-cell} ipython3
+logger.remove()
+logger.add(sys.stderr, level="WARNING")
+
+logger.debug("You don't see debug messages")
+logger.info("You also don't see info messages")
+logger.warning("But you do see all warnings")
+```
+
+## Advanced usage
+
+It is also possible to log to a file or add more information to the logs. See the
+[loguru documentation](https://loguru.readthedocs.io/) for details.

docs/source/usage/select_and_view.md

@@ -25,19 +25,6 @@ first.
 To get going, we will show the most important features of the data format using a
 toy example.
 
-```{code-cell} ipython3
-:tags: [hide-cell]
-:mystnb:
-:  code_prompt_show: "Logging setup for the docs"
-
-# setup logging for the docs - we don't need debug logs
-import sys
-from loguru import logger
-
-logger.remove()
-logger.add(sys.stderr, level="INFO")
-```
-
 ```{code-cell} ipython3
 import primap2
 import primap2.tests

primap2/__init__.py

@@ -4,6 +4,10 @@
 __email__ = "[email protected]"
 __version__ = "0.11.2"
 
+import sys
+
+from loguru import logger
+
 from . import accessors, pm2io
 from ._data_format import (
     ProcessingStepDescription,
@@ -13,6 +17,14 @@
 from ._selection import Not
 from ._units import ureg
 
+logger.remove()
+logger.add(
+    sys.stderr,
+    format="{time} <level>{level}</level> {message}",
+    level="INFO",
+    colorize=True,
+)
+
 __all__ = [
     "accessors",
     "open_dataset",

primap2/tests/conftest.py

@@ -9,7 +9,7 @@
 from . import examples
 
 
-# monkey-patch caplog to work wit loguru
+# monkey-patch caplog to work with loguru
 # see https://loguru.readthedocs.io/en/stable/resources/migration.html#making-things-work-with-pytest-and-caplog
 @pytest.fixture
 def caplog(caplog):