Deploying to gh-pages from @ ece8e3e 🚀

.gitignore

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

dev/_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 ``template`` 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 template import add_file_handler, set_log_level\nfrom template.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 `~template.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 `~template.set_log_level`. Additional file handlers can be added with\n`~template.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.10"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

dev/_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 ``template`` package
+# namespace.
+
+import logging
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from template import add_file_handler, set_log_level
+from template.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 `~template.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 `~template.set_log_level`. Additional file handlers can be added with
+# `~template.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()

dev/_sources/api/generated/template.add_file_handler.rst.txt

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

dev/_sources/api/generated/template.set_log_level.rst.txt

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

dev/_sources/api/index.rst.txt

@@ -0,0 +1,10 @@
+API References
+==============
+
+This is the reference for classes (``CamelCase`` names) and functions
+(``underscore_case`` names) of ``template-python`` grouped thematically.
+
+.. toctree::
+    :maxdepth: 2
+
+    logging.rst

dev/_sources/api/logging.rst.txt

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

dev/_sources/changes/index.rst.txt

@@ -0,0 +1,7 @@
+Changelog
+=========
+
+.. toctree::
+    :titlesonly:
+
+    latest.rst

dev/_sources/changes/latest.rst.txt

@@ -0,0 +1,38 @@
+.. NOTE: we use cross-references to highlight new functions and classes.
+   Please follow the examples below, so the changelog page will have a link to
+   the function/class documentation.
+
+.. NOTE: there are 3 separate sections for changes, based on type:
+   - "Enhancements" for new features
+   - "Bugs" for bug fixes
+   - "API changes" for backward-incompatible changes
+
+.. NOTE: You can use the :pr:`xx` and :issue:`xx` role to x-ref to a GitHub PR
+   or issue from this project.
+
+.. include:: ./authors.inc
+
+.. _latest:
+
+Version 0.1
+===========
+
+Enhancements
+------------
+
+- xxx
+
+Bugs
+----
+
+- xxx
+
+API and behavior changes
+------------------------
+
+- xxx
+
+Authors
+-------
+
+* `Mathieu Scheltienne`_