Deploying to gh-pages from @ cbdbdf7 🚀

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 25148c78e8748e73ab7331a1e6f88508
+tags: 645f666f9bcd5a90fca523b33c5a78b7

.gitignore

@@ -0,0 +1,2 @@
+# macOS
+.DS_Store

_downloads/1ecaf32698a15da6a6bf0a54b3c5fd6b/00_logging.ipynb

@@ -0,0 +1,147 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Logging\n\nThis package uses the logging module.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The logger and its utilities can be imported from the ``nmod_wiki`` package\nnamespace.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import logging\nfrom pathlib import Path\nfrom tempfile import TemporaryDirectory\n\nfrom nmod_wiki import add_file_handler, set_log_level\nfrom nmod_wiki.utils.logs import logger"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The logger can be used to send logs at different levels: ``DEBUG``, ``INFO``,\n``WARNING``, ``ERROR`` and ``CRITICAL``. Each of this level is equal to an integer\nvalue. If the logger level is at least equal to the emitted report level, the log is\ndisplayed. Else, it is omitted. By default, the logger is set to the ``WARNING``\nlevel.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "print(f\"The level 'INFO' corresponds to the value {logging.INFO}.\")\nprint(f\"The level 'ERROR' corresponds to the value {logging.ERROR}.\")\nlogger.debug(\"Log that will not be displayed.\")\nlogger.warning(\"Log that will be displayed.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The function `~nmod_wiki.set_log_level` can be used to edit the level of the logger.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "set_log_level(\"DEBUG\")\nlogger.debug(\"Log that will now be displayed.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "By default, the logger has one `~logging.StreamHandler` which outputs to\n``sys.stdout``. The level of both the logger and of this first handler can be changed\nwith `~nmod_wiki.set_log_level`. Additional file handlers can be added with\n`~nmod_wiki.add_file_handler`. Each handler can be set to a different level than the\nlogger.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>For the purpose of this example, a temporary file is used. Logs can be saved to\n    any text file, e.g. a ``.txt`` or ``.log`` file.</p></div>\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "directory = TemporaryDirectory()\nfile = Path(directory.name) / \"mylogs.log\"\nadd_file_handler(file, verbose=\"INFO\")  # different level than the logger\nlogger.debug(\"Log displayed but not saved to file.\")\nlogger.info(\"Log displayed and saved to file.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Since the file handler we added is set to the ``INFO`` level, it should capture only\nthe second log.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "with open(file) as f:\n    lines = f.readlines()\nfor line in lines:\n    print(line)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "A message level must be equal or above both the logger and the handler level to be\nemitted on a specific handler. More information on the\n[Python logging documentation](pyLogging_) and on the flowchart below:\n\n.. figure:: ../../_static/logging/flowchart-light.png\n    :class: only-light\n\n.. figure:: ../../_static/logging/flowchart-dark.png\n    :class: only-dark\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Finally, the handlers are listed in ``logger.handlers``. When an handler is not used\nanymore, it can be closed. This step is optional on Unix systems while it might be\nmantadory depending on the situation on Windows.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "print(logger.handlers)\nlogger.handlers[-1].close()"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.11.9"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

_downloads/971f2c33db2baef5789dafc0c9ad4769/00_logging.py

@@ -0,0 +1,85 @@
+"""
+Logging
+=======
+
+This package uses the logging module.
+"""
+
+# %%
+# The logger and its utilities can be imported from the ``nmod_wiki`` package
+# namespace.
+
+import logging
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from nmod_wiki import add_file_handler, set_log_level
+from nmod_wiki.utils.logs import logger
+
+# sphinx_gallery_thumbnail_path = '_static/logging/flowchart-light.png'
+
+# %%
+# The logger can be used to send logs at different levels: ``DEBUG``, ``INFO``,
+# ``WARNING``, ``ERROR`` and ``CRITICAL``. Each of this level is equal to an integer
+# value. If the logger level is at least equal to the emitted report level, the log is
+# displayed. Else, it is omitted. By default, the logger is set to the ``WARNING``
+# level.
+
+print(f"The level 'INFO' corresponds to the value {logging.INFO}.")
+print(f"The level 'ERROR' corresponds to the value {logging.ERROR}.")
+logger.debug("Log that will not be displayed.")
+logger.warning("Log that will be displayed.")
+
+# %%
+# The function `~nmod_wiki.set_log_level` can be used to edit the level of the logger.
+
+set_log_level("DEBUG")
+logger.debug("Log that will now be displayed.")
+
+# %%
+# By default, the logger has one `~logging.StreamHandler` which outputs to
+# ``sys.stdout``. The level of both the logger and of this first handler can be changed
+# with `~nmod_wiki.set_log_level`. Additional file handlers can be added with
+# `~nmod_wiki.add_file_handler`. Each handler can be set to a different level than the
+# logger.
+#
+# .. note::
+#
+#     For the purpose of this example, a temporary file is used. Logs can be saved to
+#     any text file, e.g. a ``.txt`` or ``.log`` file.
+
+directory = TemporaryDirectory()
+file = Path(directory.name) / "mylogs.log"
+add_file_handler(file, verbose="INFO")  # different level than the logger
+logger.debug("Log displayed but not saved to file.")
+logger.info("Log displayed and saved to file.")
+
+# %%
+# Since the file handler we added is set to the ``INFO`` level, it should capture only
+# the second log.
+
+with open(file) as f:
+    lines = f.readlines()
+for line in lines:
+    print(line)
+
+# %%
+# A message level must be equal or above both the logger and the handler level to be
+# emitted on a specific handler. More information on the
+# `Python logging documentation <pyLogging_>`_ and on the flowchart below:
+#
+# .. figure:: ../../_static/logging/flowchart-light.png
+#     :class: only-light
+#
+# .. figure:: ../../_static/logging/flowchart-dark.png
+#     :class: only-dark
+#
+# .. _pyLogging: https://docs.python.org/3/library/logging.html
+
+# %%
+# Finally, the handlers are listed in ``logger.handlers``. When an handler is not used
+# anymore, it can be closed. This step is optional on Unix systems while it might be
+# mantadory depending on the situation on Windows.
+
+print(logger.handlers)
+logger.handlers[-1].close()

_sources/api/generated/nmod_wiki.add_file_handler.rst.txt

@@ -0,0 +1,9 @@
+nmod\_wiki.add\_file\_handler
+=============================
+
+.. currentmodule:: nmod_wiki
+
+.. autofunction:: add_file_handler
+
+.. minigallery:: nmod_wiki.add_file_handler
+    :add-heading:

_sources/api/generated/nmod_wiki.set_log_level.rst.txt

@@ -0,0 +1,9 @@
+nmod\_wiki.set\_log\_level
+==========================
+
+.. currentmodule:: nmod_wiki
+
+.. autofunction:: set_log_level
+
+.. minigallery:: nmod_wiki.set_log_level
+    :add-heading:

_sources/api/index.rst.txt

@@ -0,0 +1,15 @@
+API References
+==============
+
+This is the reference for classes (``CamelCase`` names) and functions
+(``underscore_case`` names) of ``nmod_wiki`` grouped thematically. This package can be
+installed with ``pip`` from source:
+
+.. code-block:: bash
+
+    $ pip install git+https://github.com/fcbg-hnp-meeg/nmod-wiki
+
+.. toctree::
+    :maxdepth: 2
+
+    logging.rst

_sources/api/logging.rst.txt

@@ -0,0 +1,10 @@
+Logging
+=======
+
+.. currentmodule:: nmod_wiki
+
+.. autosummary::
+    :toctree: generated/
+
+    add_file_handler
+    set_log_level