logger-36 2024.1__py3-none-any.whl → 2024.2__py3-none-any.whl

logger_36/main.py

@@ -29,68 +29,166 @@
 # The fact that you are presently reading this means that you have had
 # knowledge of the CeCILL license and that you accept its terms.
 
-"""
-Alternative implementations: using logging.Filter or logging.LoggerAdapter.
-"""
 import logging as lggg
+import sys as sstm
 from pathlib import Path as path_t
-from typing import Callable, Literal
 
+try:
+    from logger_36.catalog.handler.console_rich import console_rich_handler_t
+
+    _RICH_ERROR = None
+except ModuleNotFoundError:
+    from logger_36.catalog.handler.console import (
+        console_handler_t as console_rich_handler_t,
+    )
+
+    _RICH_ERROR = (
+        "The Rich console handler is not available, "
+        "probably because the Rich package "
+        "(https://rich.readthedocs.io/en/stable/index.html) "
+        "is not installed, or not loadable. "
+        "Falling back to the raw console."
+    )
+from logger_36.catalog.handler.console import console_handler_t
+from logger_36.catalog.handler.file import file_handler_t
+from logger_36.catalog.handler.generic import generic_handler_t, interface_h
+from logger_36.constant.handler import HANDLER_CODES, handler_codes_h
 from logger_36.instance import LOGGER
-from logger_36.type.console import console_handler_t
-from logger_36.type.file import file_handler_t
-from logger_36.type.generic import can_show_message_p, generic_handler_t
+from logger_36.task.format.message import FormattedMessage
 
 
 def AddGenericHandler(
-    interface: can_show_message_p | Callable[[str], None],
+    interface: interface_h,
     /,
-    *args,
+    *,
+    name: str | None = None,
     level: int = lggg.INFO,
+    show_where: bool = True,
+    show_memory_usage: bool = False,
+    formatter: lggg.Formatter | None = None,
     supports_html: bool = False,
+    should_hold_messages: bool = False,
+    **kwargs,
+) -> None:
+    """"""
+    handler = generic_handler_t(
+        name=name,
+        level=level,
+        show_where=show_where,
+        show_memory_usage=show_memory_usage,
+        formatter=formatter,
+        supports_html=supports_html,
+        rich_kwargs=kwargs,
+        interface=interface,
+    )
+    LOGGER.AddHandler(handler, should_hold_messages)
+
+
+def AddConsoleHandler(
+    *,
+    name: str | None = None,
+    level: int = lggg.INFO,
+    show_where: bool = True,
+    show_memory_usage: bool = False,
+    formatter: lggg.Formatter | None = None,
+    should_hold_messages: bool = False,
+) -> None:
+    """"""
+    handler = console_handler_t(
+        name=name,
+        level=level,
+        show_where=show_where,
+        show_memory_usage=show_memory_usage,
+        formatter=formatter,
+    )
+    LOGGER.AddHandler(handler, should_hold_messages)
+
+
+def AddRichConsoleHandler(
+    *,
+    name: str | None = None,
+    level: int = lggg.INFO,
+    show_where: bool = True,
+    show_memory_usage: bool = False,
+    formatter: lggg.Formatter | None = None,
+    should_hold_messages: bool = False,
     **kwargs,
 ) -> None:
     """"""
-    handler = generic_handler_t(interface, *args, supports_html=supports_html, **kwargs)
-    handler.setLevel(level)
-    LOGGER.addHandler(handler)
+    global _RICH_ERROR
+    if _RICH_ERROR is not None:
+        print(_RICH_ERROR, file=sstm.stderr)
+        _RICH_ERROR = None
+
+    handler = console_rich_handler_t(
+        name=name,
+        level=level,
+        show_where=show_where,
+        show_memory_usage=show_memory_usage,
+        formatter=formatter,
+        rich_kwargs=kwargs,
+    )
+    LOGGER.AddHandler(handler, should_hold_messages)
 
 
 def AddFileHandler(
-    path: str | path_t, /, *args, level: int = lggg.INFO, **kwargs
+    path: str | path_t,
+    /,
+    *args,
+    name: str | None = None,
+    level: int = lggg.INFO,
+    show_where: bool = True,
+    show_memory_usage: bool = False,
+    formatter: lggg.Formatter | None = None,
+    should_hold_messages: bool = False,
+    **kwargs,
 ) -> None:
     """"""
     if isinstance(path, str):
         path = path_t(path)
     if path.exists():
-        raise ValueError(f"{path}: File already exists")
+        raise ValueError(f"File or folder already exists: {path}.")
 
-    handler = file_handler_t(path, *args, **kwargs)
-    handler.setLevel(level)
-    LOGGER.addHandler(handler)
+    handler = file_handler_t(
+        name=name,
+        level=level,
+        show_where=show_where,
+        show_memory_usage=show_memory_usage,
+        formatter=formatter,
+        path=path,
+        handler_args=args,
+        handler_kwargs=kwargs,
+    )
+    LOGGER.AddHandler(handler, should_hold_messages)
 
 
-def SetLOGLevel(level: int, /, *, which: Literal["c", "f", "a"] = "a") -> None:
+def SetLOGLevel(level: int, /, *, which: handler_codes_h | str = "a") -> None:
     """
-    which: c=console, f=file, a=all
+    which: g=generic, c=console, f=file, a=all, str=name.
     """
-    if which not in "cfa":
-        raise ValueError(
-            f"{which}: Invalid handler specifier. "
-            f'Expected="c" for console, "f" for file, or "a" for all'
-        )
-
+    which_is_name = which not in HANDLER_CODES
+    found = False
     for handler in LOGGER.handlers:
         if (
             (which == "a")
-            or ((which == "c") and isinstance(handler, console_handler_t))
+            or ((which == "g") and isinstance(handler, generic_handler_t))
+            or (
+                (which == "c")
+                and isinstance(handler, (console_handler_t, console_rich_handler_t))
+            )
             or ((which == "f") and isinstance(handler, file_handler_t))
+            or (which == handler.name)
         ):
             handler.setLevel(level)
+            if which_is_name:
+                return
+            found = True
 
-
-def SetExitOnError(exit_on_error: bool, /) -> None:
-    """"""
-    for handler in LOGGER.handlers:
-        if hasattr(handler, "exit_on_error"):
-            handler.exit_on_error = exit_on_error
+    if not found:
+        raise ValueError(
+            FormattedMessage(
+                "Handler not found",
+                actual=which,
+                expected=f"{str(HANDLER_CODES)[1:-1]}, or a handler name",
+            )
+        )

logger_36/{catalog → task/format}/memory.py

@@ -29,65 +29,54 @@
 # The fact that you are presently reading this means that you have had
 # knowledge of the CeCILL license and that you accept its terms.
 
-from typing import Literal
+from logger_36.constant.memory import STORAGE_UNITS, storage_units_h
+from logger_36.task.format.message import FormattedMessage
 
-from logger_36.instance import LOGGER
-from logger_36.measure.memory import CanCheckMemory
+_KILO_UNIT = 1000.0
+_MEGA_UNIT = _KILO_UNIT * 1000.0
+_GIGA_UNIT = _MEGA_UNIT * 1000.0
 
-_KILO_UNIT = 1024.0
-_MEGA_UNIT = _KILO_UNIT * 1024.0
-_GIGA_UNIT = _MEGA_UNIT * 1024.0
-
-
-def SetShowMemoryUsage(show_memory_usage: bool, /) -> None:
-    """"""
-    if show_memory_usage and not CanCheckMemory():
-        LOGGER.warning('Cannot show memory usage: Package "psutil" not installed')
-        return
-
-    for handler in LOGGER.handlers:
-        if hasattr(handler, "show_memory_usage"):
-            handler.show_memory_usage = show_memory_usage
+_BLOCKS_PARTIAL = ("", "▏", "▎", "▍", "▌", "▋", "▊")
+_BLOCK_FULL = "▉"
 
 
 def FormattedUsage(
     usage: int,
     /,
     *,
-    unit: Literal["b", "k", "m", "g", "a"] | None = "a",
+    unit: storage_units_h | None = "a",
     decimals: int = None,
 ) -> tuple[int | float, str]:
     """
     unit: b or None=bytes, k=kilo, m=mega, g=giga, a=auto
     """
     if (unit is None) or (unit == "b"):
+        value = usage
         unit = "B"
     elif unit == "k":
-        usage = _Rounded(usage / _KILO_UNIT, decimals)
+        value = _Rounded(usage / _KILO_UNIT, decimals)
         unit = "KB"
     elif unit == "m":
-        usage = _Rounded(usage / _MEGA_UNIT, decimals)
+        value = _Rounded(usage / _MEGA_UNIT, decimals)
         unit = "MB"
     elif unit == "g":
-        usage = _Rounded(usage / _GIGA_UNIT, decimals)
+        value = _Rounded(usage / _GIGA_UNIT, decimals)
         unit = "GB"
     elif unit == "a":
-        usage, unit = WithAutoUnit(usage, decimals)
+        value, unit = FormattedUsageWithAutoUnit(usage, decimals)
+    else:
+        raise ValueError(
+            FormattedMessage(
+                "Invalid unit", actual=unit, expected=str(STORAGE_UNITS)[1:-1]
+            )
+        )
 
-    return usage, unit
+    return value, unit
 
 
-def MaximumUsage(
-    *, unit: Literal["b", "k", "m", "g", "a"] | None = "a", decimals: int = None
+def FormattedUsageWithAutoUnit(
+    usage: int, decimals: int | None, /
 ) -> tuple[int | float, str]:
-    """
-    unit: b or None=bytes, k=kilo, m=mega, g=giga, a=auto
-    """
-    usage = max(getattr(_hdr, "max_memory_usage", -1) for _hdr in LOGGER.handlers)
-    return FormattedUsage(usage, unit=unit, decimals=decimals)
-
-
-def WithAutoUnit(usage: int, decimals: int | None, /) -> tuple[int | float, str]:
     """"""
     if usage > _GIGA_UNIT:
         return _Rounded(usage / _GIGA_UNIT, decimals), "GB"
@@ -101,6 +90,18 @@ def WithAutoUnit(usage: int, decimals: int | None, /) -> tuple[int | float, str]
     return usage, "B"
 
 
+def UsageBar(
+    usage: int | float, max_usage: int | float, /, *, length_100: int = 10
+) -> str:
+    """"""
+    length = (usage / max_usage) * length_100
+    n_full_s = int(length)
+    return (
+        n_full_s * _BLOCK_FULL
+        + _BLOCKS_PARTIAL[int((2.0 / 3.0) * int(10 * (length - n_full_s)))]
+    )
+
+
 def _Rounded(value: float, decimals: int | None, /) -> int | float:
     """"""
     if decimals == 0:

logger_36/task/format/message.py

@@ -0,0 +1,112 @@
+# Copyright CNRS/Inria/UCA
+# Contributor(s): Eric Debreuve (since 2023)
+#
+# eric.debreuve@cnrs.fr
+#
+# This software is governed by the CeCILL  license under French law and
+# abiding by the rules of distribution of free software.  You can  use,
+# modify and/ or redistribute the software under the terms of the CeCILL
+# license as circulated by CEA, CNRS and INRIA at the following URL
+# "http://www.cecill.info".
+#
+# As a counterpart to the access to the source code and  rights to copy,
+# modify and redistribute granted by the license, users are provided only
+# with a limited warranty  and the software's author,  the holder of the
+# economic rights,  and the successive licensors  have only  limited
+# liability.
+#
+# In this respect, the user's attention is drawn to the risks associated
+# with loading,  using,  modifying and/or developing or reproducing the
+# software by the user in light of its specific status of free software,
+# that may mean  that it is complicated to manipulate,  and  that  also
+# therefore means  that it is reserved for developers  and  experienced
+# professionals having in-depth computer knowledge. Users are therefore
+# encouraged to load and test the software's suitability as regards their
+# requirements in conditions enabling the security of their systems and/or
+# data to be ensured and,  more generally, to use and operate it in the
+# same conditions as regards security.
+#
+# The fact that you are presently reading this means that you have had
+# knowledge of the CeCILL license and that you accept its terms.
+
+import typing as h
+
+from logger_36.config.message import (
+    ELAPSED_TIME_FORMAT,
+    LEVEL_CLOSING,
+    LEVEL_OPENING,
+    MEMORY_FORMAT,
+    MESSAGE_MARKER,
+)
+from logger_36.constant.generic import NOT_PASSED
+from logger_36.constant.message import EXPECTED_OP, expected_op_h
+
+
+def MessageFormat(with_where: bool, with_memory_usage: bool, /) -> str:
+    """"""
+    output = [
+        f"%(asctime)s"
+        f"{LEVEL_OPENING}%(level_first_letter)s{LEVEL_CLOSING}\t"
+        f"{MESSAGE_MARKER}%(message)s"
+    ]
+
+    if with_where:
+        output.append("%(where)s")
+    output.append(ELAPSED_TIME_FORMAT)
+    if with_memory_usage:
+        output.append(MEMORY_FORMAT)
+
+    return "".join(output)
+
+
+def FormattedMessage(
+    message: str,
+    /,
+    *,
+    actual: h.Any = NOT_PASSED,
+    expected: h.Any | None = None,
+    expected_op: expected_op_h = "=",
+    with_final_dot: bool = True,
+) -> str:
+    """"""
+    if expected_op not in EXPECTED_OP:
+        raise ValueError(
+            FormattedMessage(
+                'Invalid "expected" section operator',
+                actual=expected_op,
+                expected=f"One of {str(EXPECTED_OP)[1:-1]}",
+            )
+        )
+
+    if actual is NOT_PASSED:
+        if with_final_dot:
+            if message[-1] != ".":
+                message += "."
+        elif message[-1] == ".":
+            message = message[:-1]
+
+        return message
+
+    if message[-1] == ".":
+        message = message[:-1]
+    actual = _FormattedValue(actual)
+    expected = _FormattedValue(expected)
+
+    if with_final_dot:
+        dot = "."
+    else:
+        dot = ""
+    return f"{message}: Actual={actual}; Expected{expected_op}{expected}{dot}"
+
+
+def _FormattedValue(value: h.Any, /, *, should_format_str: bool = True) -> str:
+    """"""
+    if value is None:
+        return "None"
+
+    if isinstance(value, str):
+        if should_format_str:
+            return f'"{value}"'
+        return value
+
+    return str(value)

logger_36/task/format/rule.py

@@ -0,0 +1,47 @@
+# Copyright CNRS/Inria/UCA
+# Contributor(s): Eric Debreuve (since 2023)
+#
+# eric.debreuve@cnrs.fr
+#
+# This software is governed by the CeCILL  license under French law and
+# abiding by the rules of distribution of free software.  You can  use,
+# modify and/ or redistribute the software under the terms of the CeCILL
+# license as circulated by CEA, CNRS and INRIA at the following URL
+# "http://www.cecill.info".
+#
+# As a counterpart to the access to the source code and  rights to copy,
+# modify and redistribute granted by the license, users are provided only
+# with a limited warranty  and the software's author,  the holder of the
+# economic rights,  and the successive licensors  have only  limited
+# liability.
+#
+# In this respect, the user's attention is drawn to the risks associated
+# with loading,  using,  modifying and/or developing or reproducing the
+# software by the user in light of its specific status of free software,
+# that may mean  that it is complicated to manipulate,  and  that  also
+# therefore means  that it is reserved for developers  and  experienced
+# professionals having in-depth computer knowledge. Users are therefore
+# encouraged to load and test the software's suitability as regards their
+# requirements in conditions enabling the security of their systems and/or
+# data to be ensured and,  more generally, to use and operate it in the
+# same conditions as regards security.
+#
+# The fact that you are presently reading this means that you have had
+# knowledge of the CeCILL license and that you accept its terms.
+
+
+def RuleAsText(text: str, /) -> str:
+    """"""
+    return f"---- ---- ---- ---- {text} ---- ---- ---- ----"
+
+
+try:
+    from rich.rule import Rule as rule_t
+    from rich.text import Text as text_t
+
+    def Rule(text: str, color: str, /) -> rule_t:
+        """"""
+        return rule_t(title=text_t(text, style=f"bold {color}"), style=color)
+
+except ModuleNotFoundError:
+    Rule = lambda _txt, _: RuleAsText(_txt)

logger_36/task/inspection.py

@@ -36,14 +36,15 @@ from types import FunctionType, MethodType
 
 
 def Modules(
-    with_version: bool, formatted: bool, /, *, only_loaded: bool = True
+    with_version: bool, formatted: bool, /, *, only_loaded: bool = True, indent: int = 0
 ) -> tuple[str, ...] | str:
     """"""
     output = []
 
     if only_loaded:
         modules = sstm.modules
-        module_names = sorted(modules.keys(), key=str.lower)
+        module_names = set(modules.keys()).difference(sstm.stdlib_module_names)
+        module_names = sorted(module_names, key=str.lower)
     else:
         modules = None
         module_names = _ModulesUsingPkgUtil()
@@ -53,35 +54,34 @@ def Modules(
         if name.startswith("_") or ("." in name):
             continue
 
-        if modules is None:
-            version = "?version?"
-        else:
-            module = modules[name]
-            version = getattr(module, "__version__", None)
-            if version is None:
-                continue
-
-        if formatted and (m_idx > 0) and (m_idx % 4 == 0):
-            output.append("\n")
-
         if with_version:
+            if modules is None:
+                version = "?"
+            else:
+                module = modules[name]
+                # strip: Some packages have a \n at the end of their version. Just in
+                # case, let's strip it left and right.
+                version = getattr(module, "__version__", "?").strip()
             element = f"{name}={version}"
         else:
             element = name
+
+        if formatted and (m_idx > 0) and (m_idx % 4 == 0):
+            output.append("\n")
         output.append(element)
 
         if formatted:
-            max_length = max(max_length, name.__len__() + version.__len__() + 1)
+            max_length = max(max_length, element.__len__())
             m_idx += 1
 
     if formatted:
         max_length += 4
-        AlignedInColumns = lambda _str: (
-            f"{_str:{max_length}}" if _str != "\n" else "\n    "
-        )
+        AlignedInColumns = lambda _str: f"{_str:{max_length}}" if _str != "\n" else "\n"
         output = map(AlignedInColumns, output)
+        output = "".join(output).rstrip()
 
-        return "".join(output)
+        spaces = indent * " "
+        return spaces + f"\n{spaces}".join(map(str.rstrip, output.splitlines()))
 
     return tuple(output)
 

logger_36/{measure → task/measure}/chronos.py

@@ -32,7 +32,9 @@
 import time
 from datetime import datetime as dttm
 
-from logger_36.constant import START_TIME
+# This module is imported early. Therefore, the current date and time should be close
+# enough to the real start time of the main script.
+_START_DATE_AND_TIME = dttm.now()
 
 
 def TimeStamp() -> str:
@@ -47,7 +49,7 @@ def TimeStamp() -> str:
 
 def ElapsedTime() -> str:
     """"""
-    elapsed_seconds = (dttm.now() - START_TIME).total_seconds()
+    elapsed_seconds = (dttm.now() - _START_DATE_AND_TIME).total_seconds()
     output = time.strftime("%Hh %Mm %Ss", time.gmtime(elapsed_seconds))
     while output.startswith("00") and (" " in output):
         output = output.split(maxsplit=1)[-1]

logger_36/task/storage.py

@@ -29,21 +29,82 @@
 # The fact that you are presently reading this means that you have had
 # knowledge of the CeCILL license and that you accept its terms.
 
+import dataclasses as dtcl
 import logging as lggg
+import re as regx
+import typing as h
+from html.parser import HTMLParser as html_parser_t
 from pathlib import Path as path_t
-from typing import TextIO
 
-from rich.console import Console as console_t
+try:
+    from rich.console import Console as console_t
+except ModuleNotFoundError:
+    console_t = None
 
 from logger_36.instance import LOGGER
 
 
-def SaveLOGasHTML(path: str | path_t | TextIO = None) -> None:
+@dtcl.dataclass(slots=True, repr=False, eq=False)
+class html_reader_t(html_parser_t):
+    BODY_END_PATTERN: h.ClassVar[str] = r"</[bB][oO][dD][yY]>(.|\n)*$"
+
+    source: str = ""
+    inside_body: bool = dtcl.field(init=False, default=False)
+    body_position_start: tuple[int, int] = dtcl.field(init=False, default=(-1, -1))
+    body_position_end: tuple[int, int] = dtcl.field(init=False, default=(-1, -1))
+    pieces: list[str] = dtcl.field(init=False, default_factory=list)
+
+    def __post_init__(self) -> None:
+        """"""
+        html_parser_t.__init__(self)
+        self.source = self.source.strip()
+        self.feed(self.source)
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]], /) -> None:
+        """"""
+        if tag == "body":
+            self.body_position_start = self.getpos()
+            self.inside_body = True
+
+    def handle_endtag(self, tag: str, /) -> None:
+        """"""
+        if tag == "body":
+            self.body_position_end = self.getpos()
+            self.inside_body = False
+
+    def handle_data(self, data: str, /) -> None:
+        """"""
+        if self.inside_body:
+            self.pieces.append(data)
+
+    @property
+    def body(self) -> str:
+        """"""
+        output = self.source.splitlines()
+        output = "\n".join(
+            output[self.body_position_start[0] : (self.body_position_end[0] + 1)]
+        )
+        output = output[self.body_position_start[1] :]
+        output = regx.sub(self.__class__.BODY_END_PATTERN, "", output, count=1)
+
+        return output.strip()
+
+    @property
+    def body_as_text(self) -> str:
+        """"""
+        return "".join(self.pieces).strip()
+
+
+def SaveLOGasHTML(path: str | path_t | h.TextIO = None) -> None:
     """
     From first console handler found.
     """
     cannot_save = "Cannot save logging record as HTML"
 
+    if console_t is None:
+        LOGGER.warning(f"{cannot_save}: The Rich console cannot be imported.")
+        return
+
     if path is None:
         for handler in LOGGER.handlers:
             if isinstance(handler, lggg.FileHandler):