diff --git a/changelog/279.enhancement.md b/changelog/279.enhancement.md new file mode 100644 index 0000000..ec4b400 --- /dev/null +++ b/changelog/279.enhancement.md @@ -0,0 +1 @@ +We now skip debug messages in the default logger. diff --git a/docs/source/usage/index.md b/docs/source/usage/index.md index aa12200..9b23fd3 100644 --- a/docs/source/usage/index.md +++ b/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 diff --git a/docs/source/usage/logging.md b/docs/source/usage/logging.md new file mode 100644 index 0000000..484f025 --- /dev/null +++ b/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. diff --git a/docs/source/usage/select_and_view.md b/docs/source/usage/select_and_view.md index 9c3ba34..70542aa 100644 --- a/docs/source/usage/select_and_view.md +++ b/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 diff --git a/primap2/__init__.py b/primap2/__init__.py index d36688c..0395379 100644 --- a/primap2/__init__.py +++ b/primap2/__init__.py @@ -4,6 +4,10 @@ __email__ = "mika.pflueger@climate-resource.com" __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} {message}", + level="INFO", + colorize=True, +) + __all__ = [ "accessors", "open_dataset", diff --git a/primap2/tests/conftest.py b/primap2/tests/conftest.py index 8bb5e1c..b105783 100644 --- a/primap2/tests/conftest.py +++ b/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):