Skip to content

Commit a462d98

Browse files
github-actions[bot]github-actions[bot]
committed
Deploying to gh-pages from @ 76437c5 🚀
0 parents  commit a462d98

79 files changed

Lines changed: 9305 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# macOS
2+
.DS_Store

‎.nojekyll‎

Whitespace-only changes.

‎dev/_downloads/1ecaf32698a15da6a6bf0a54b3c5fd6b/00_logging.ipynb‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"\n# Logging\n\nThis package uses the logging module.\n"
8+
]
9+
},
10+
{
11+
"cell_type": "markdown",
12+
"metadata": {},
13+
"source": [
14+
"The logger and its utilities can be imported from the ``template`` package\nnamespace.\n\n"
15+
]
16+
},
17+
{
18+
"cell_type": "code",
19+
"execution_count": null,
20+
"metadata": {
21+
"collapsed": false
22+
},
23+
"outputs": [],
24+
"source": [
25+
"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"
26+
]
27+
},
28+
{
29+
"cell_type": "markdown",
30+
"metadata": {},
31+
"source": [
32+
"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"
33+
]
34+
},
35+
{
36+
"cell_type": "code",
37+
"execution_count": null,
38+
"metadata": {
39+
"collapsed": false
40+
},
41+
"outputs": [],
42+
"source": [
43+
"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.\")"
44+
]
45+
},
46+
{
47+
"cell_type": "markdown",
48+
"metadata": {},
49+
"source": [
50+
"The function `~template.set_log_level` can be used to edit the level of the logger.\n\n"
51+
]
52+
},
53+
{
54+
"cell_type": "code",
55+
"execution_count": null,
56+
"metadata": {
57+
"collapsed": false
58+
},
59+
"outputs": [],
60+
"source": [
61+
"set_log_level(\"DEBUG\")\nlogger.debug(\"Log that will now be displayed.\")"
62+
]
63+
},
64+
{
65+
"cell_type": "markdown",
66+
"metadata": {},
67+
"source": [
68+
"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"
69+
]
70+
},
71+
{
72+
"cell_type": "code",
73+
"execution_count": null,
74+
"metadata": {
75+
"collapsed": false
76+
},
77+
"outputs": [],
78+
"source": [
79+
"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.\")"
80+
]
81+
},
82+
{
83+
"cell_type": "markdown",
84+
"metadata": {},
85+
"source": [
86+
"Since the file handler we added is set to the ``INFO`` level, it should capture only\nthe second log.\n\n"
87+
]
88+
},
89+
{
90+
"cell_type": "code",
91+
"execution_count": null,
92+
"metadata": {
93+
"collapsed": false
94+
},
95+
"outputs": [],
96+
"source": [
97+
"with open(file) as f:\n lines = f.readlines()\nfor line in lines:\n print(line)"
98+
]
99+
},
100+
{
101+
"cell_type": "markdown",
102+
"metadata": {},
103+
"source": [
104+
"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"
105+
]
106+
},
107+
{
108+
"cell_type": "markdown",
109+
"metadata": {},
110+
"source": [
111+
"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"
112+
]
113+
},
114+
{
115+
"cell_type": "code",
116+
"execution_count": null,
117+
"metadata": {
118+
"collapsed": false
119+
},
120+
"outputs": [],
121+
"source": [
122+
"print(logger.handlers)\nlogger.handlers[-1].close()"
123+
]
124+
}
125+
],
126+
"metadata": {
127+
"kernelspec": {
128+
"display_name": "Python 3",
129+
"language": "python",
130+
"name": "python3"
131+
},
132+
"language_info": {
133+
"codemirror_mode": {
134+
"name": "ipython",
135+
"version": 3
136+
},
137+
"file_extension": ".py",
138+
"mimetype": "text/x-python",
139+
"name": "python",
140+
"nbconvert_exporter": "python",
141+
"pygments_lexer": "ipython3",
142+
"version": "3.12.3"
143+
}
144+
},
145+
"nbformat": 4,
146+
"nbformat_minor": 0
147+
}

‎dev/_downloads/971f2c33db2baef5789dafc0c9ad4769/00_logging.py‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
"""
2+
Logging
3+
=======
4+
5+
This package uses the logging module.
6+
"""
7+
8+
# %%
9+
# The logger and its utilities can be imported from the ``template`` package
10+
# namespace.
11+
12+
import logging
13+
from pathlib import Path
14+
from tempfile import TemporaryDirectory
15+
16+
from template import add_file_handler, set_log_level
17+
from template.utils.logs import logger
18+
19+
# sphinx_gallery_thumbnail_path = '_static/logging/flowchart-light.png'
20+
21+
# %%
22+
# The logger can be used to send logs at different levels: ``DEBUG``, ``INFO``,
23+
# ``WARNING``, ``ERROR`` and ``CRITICAL``. Each of this level is equal to an integer
24+
# value. If the logger level is at least equal to the emitted report level, the log is
25+
# displayed. Else, it is omitted. By default, the logger is set to the ``WARNING``
26+
# level.
27+
28+
print(f"The level 'INFO' corresponds to the value {logging.INFO}.")
29+
print(f"The level 'ERROR' corresponds to the value {logging.ERROR}.")
30+
logger.debug("Log that will not be displayed.")
31+
logger.warning("Log that will be displayed.")
32+
33+
# %%
34+
# The function `~template.set_log_level` can be used to edit the level of the logger.
35+
36+
set_log_level("DEBUG")
37+
logger.debug("Log that will now be displayed.")
38+
39+
# %%
40+
# By default, the logger has one `~logging.StreamHandler` which outputs to
41+
# ``sys.stdout``. The level of both the logger and of this first handler can be changed
42+
# with `~template.set_log_level`. Additional file handlers can be added with
43+
# `~template.add_file_handler`. Each handler can be set to a different level than the
44+
# logger.
45+
#
46+
# .. note::
47+
#
48+
# For the purpose of this example, a temporary file is used. Logs can be saved to
49+
# any text file, e.g. a ``.txt`` or ``.log`` file.
50+
51+
directory = TemporaryDirectory()
52+
file = Path(directory.name) / "mylogs.log"
53+
add_file_handler(file, verbose="INFO") # different level than the logger
54+
logger.debug("Log displayed but not saved to file.")
55+
logger.info("Log displayed and saved to file.")
56+
57+
# %%
58+
# Since the file handler we added is set to the ``INFO`` level, it should capture only
59+
# the second log.
60+
61+
with open(file) as f:
62+
lines = f.readlines()
63+
for line in lines:
64+
print(line)
65+
66+
# %%
67+
# A message level must be equal or above both the logger and the handler level to be
68+
# emitted on a specific handler. More information on the
69+
# `Python logging documentation <pyLogging_>`_ and on the flowchart below:
70+
#
71+
# .. figure:: ../../_static/logging/flowchart-light.png
72+
# :class: only-light
73+
#
74+
# .. figure:: ../../_static/logging/flowchart-dark.png
75+
# :class: only-dark
76+
#
77+
# .. _pyLogging: https://docs.python.org/3/library/logging.html
78+
79+
# %%
80+
# Finally, the handlers are listed in ``logger.handlers``. When an handler is not used
81+
# anymore, it can be closed. This step is optional on Unix systems while it might be
82+
# mantadory depending on the situation on Windows.
83+
84+
print(logger.handlers)
85+
logger.handlers[-1].close()

‎dev/_downloads/9d554c47ca875f7ea767f890b94bedca/tutorials_jupyter.zip‎

5.13 KB
Binary file not shown.

‎dev/_downloads/9f21271df84336fe94703eeca49361ac/00_logging.zip‎

8 KB
Binary file not shown.

‎dev/_downloads/f39435c137e7c92d0a271e51aa1187ac/tutorials_python.zip‎

2.89 KB
Binary file not shown.

‎dev/_images/flowchart-dark.png‎

60.8 KB
Loading

‎dev/_images/flowchart-light.png‎

48.5 KB
Loading

‎dev/_images/sphx_glr_00_logging_thumb.png‎

19 KB
Loading

0 commit comments

Comments
 (0)