ft-logger 2026.1__py3-none-any.whl

ft_logger/__init__.py

@@ -0,0 +1,24 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+try:
+    from beartype.claw import beartype_this_package  # noqa
+except ModuleNotFoundError:
+    pass
+else:
+    import site
+    from pathlib import Path as path_t
+
+    folder = path_t(__file__).parent
+    paths = site.getsitepackages() + [site.getusersitepackages()]
+    for path in paths:
+        if folder.is_relative_to(path):
+            break
+    else:
+        beartype_this_package()
+
+from .version import __version__  # noqa
+from .instance.logger import L  # noqa

ft_logger/api/chronos.py

@@ -0,0 +1,8 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+from ..task.format.chronos import FormattedElapsedTime  # noqa
+from ..task.measure.chronos import TimeStamp  # noqa

ft_logger/api/handler.py

@@ -0,0 +1,7 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+from ..type.theme import theme_t  # noqa

ft_logger/api/logger.py

@@ -0,0 +1,7 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+from ..type.logger import logger_t  # noqa

ft_logger/api/memory.py

@@ -0,0 +1,12 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+from ..catalog.config.optional import MEMORY_MEASURE_IS_AVAILABLE  # noqa
+from ..task.format.memory import FormattedUsage as FormattedMemoryUsage  # noqa
+from ..task.format.memory import (  # noqa
+    FormattedUsageWithAutoUnit as FormattedMemoryUsageWithAutoUnit,
+)
+from ..task.measure.memory import CurrentUsage as CurrentMemoryUsage  # noqa

ft_logger/api/message.py

@@ -0,0 +1,8 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+from ..constant.message import LINE_INDENT  # noqa
+from ..task.format.message import MessageWithActualExpected  # noqa

ft_logger/catalog/config/optional.py

@@ -0,0 +1,33 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+try:
+    import psutil  # noqa
+except ModuleNotFoundError:
+    MEMORY_MEASURE_IS_AVAILABLE = False
+    from ...constant.error import MISSING_MEMORY_MEASURE_MESSAGE
+else:
+    MEMORY_MEASURE_IS_AVAILABLE = True
+    MISSING_MEMORY_MEASURE_MESSAGE = None
+
+try:
+    import rich  # noqa
+except ModuleNotFoundError:
+    RICH_IS_AVAILABLE = False
+    from ...constant.error import MISSING_RICH_MESSAGE
+else:
+    RICH_IS_AVAILABLE = True
+    MISSING_RICH_MESSAGE = None
+
+try:
+    import tensorflow  # noqa
+    import tensorrt  # noqa
+except ModuleNotFoundError:
+    GPU_LOGGING_IS_AVAILABLE = False
+    from ...constant.error import MISSING_GPU_LOGGING_MESSAGE
+else:
+    GPU_LOGGING_IS_AVAILABLE = True
+    MISSING_GPU_LOGGING_MESSAGE = None

ft_logger/catalog/config/theme_on_dark.py

@@ -0,0 +1,23 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+import logging as l
+
+TEXT_COLOR = "grey85"
+WHERE_COLOR = "grey58"
+
+LEVEL_COLOR = {
+    l.DEBUG: "orchid",
+    l.INFO: WHERE_COLOR,
+    l.WARNING: "yellow1",
+    l.ERROR: "dark_orange",
+    l.CRITICAL: "bright_red",
+}
+ACTUAL_COLOR = LEVEL_COLOR[l.CRITICAL]
+EXPECTED_COLOR = "green3"
+RULE_COLOR = "sky_blue3"
+
+ALTERNATIVE_BACKGROUND = (15, 15, 15)

ft_logger/catalog/config/theme_on_light.py

@@ -0,0 +1,23 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+import logging as l
+
+TEXT_COLOR = "grey27"
+WHERE_COLOR = "grey46"
+
+LEVEL_COLOR = {
+    l.DEBUG: "orchid",
+    l.INFO: WHERE_COLOR,
+    l.WARNING: "light_goldenrod3",
+    l.ERROR: "dark_orange",
+    l.CRITICAL: "bright_red",
+}
+ACTUAL_COLOR = LEVEL_COLOR[l.CRITICAL]
+EXPECTED_COLOR = "green3"
+RULE_COLOR = "dodger_blue1"
+
+ALTERNATIVE_BACKGROUND = (230, 230, 230)

ft_logger/catalog/handler/color_rich.py

@@ -0,0 +1,159 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+import logging as l
+import sys as s
+import typing as h
+
+from ...config.message import ACTUAL_PATTERNS, EXPECTED_PATTERN, FALLBACK_PAGE_WIDTH
+from ...constant.color import COLORS_TERMINAL_256
+from ...constant.message import CONTEXT_LENGTH_p_1
+from ...extension.object import DefaultNameFor
+from ...task.conversion.record import MessageFromRecord
+from ...type.theme import theme_t
+from ..config.optional import MISSING_RICH_MESSAGE, RICH_IS_AVAILABLE
+
+if RICH_IS_AVAILABLE:
+    from rich.color import Color as color_t  # noqa
+    from rich.console import Console as console_t  # noqa
+    from rich.markup import escape as EscapedVersion  # noqa
+    from rich.rule import Rule as rule_t  # noqa
+    from rich.style import Style as style_t  # noqa
+    from rich.text import Text as text_t  # noqa
+    from rich.traceback import install as InstallTracebackHandler  # noqa
+
+    _COMMON_TRACEBACK_ARGUMENTS = ("theme", "width")
+    _EXCLUSIVE_TRACEBACK_ARGUMENTS = (
+        "extra_lines",
+        "indent_guides",
+        "locals_hide_dunder",
+        "locals_hide_sunder",
+        "locals_max_length",
+        "locals_max_string",
+        "max_framesshow_locals",
+        "suppress",
+        "word_wrap",
+    )
+
+    base_t = l.Handler
+
+    class color_rich_handler_t(base_t):
+        def __init__(self, *_, **kwargs) -> None:
+            """"""
+            base_t.__init__(self)
+
+            self.name: str = kwargs.pop("name", DefaultNameFor(self))
+            self.page_width: int = kwargs.pop("page_width", -1)
+            self.wrapping_is_disabled = True
+            self.theme: str | theme_t | None = kwargs.pop("theme", None)
+            self.console: console_t | None = None
+            self.should_install_traceback: bool = kwargs.pop(
+                "should_install_traceback", False
+            )
+            self.DoEmit: h.Callable | None = None
+            self.FlushStream: h.Callable | None = None
+
+            self.__post_init__(kwargs.pop("level", l.INFO), **kwargs)
+
+        def __post_init__(self, level: int, /, **kwargs) -> None:
+            """"""
+            self.setLevel(level)
+
+            if 0 < self.page_width < FALLBACK_PAGE_WIDTH:
+                # Prevent message width from being "unrealistically" small.
+                self.page_width = FALLBACK_PAGE_WIDTH
+            self.wrapping_is_disabled = self.page_width <= 0
+
+            if self.theme is None:
+                self.theme = theme_t.NewDefault("rich", "dark")
+            elif isinstance(self.theme, str):
+                self.theme = theme_t.NewDefaultFromStr(self.theme)
+            MakeThemeRich(self.theme)
+
+            traceback_kwargs = {}
+            if self.should_install_traceback:
+                for key in kwargs:
+                    if key in _COMMON_TRACEBACK_ARGUMENTS:
+                        traceback_kwargs[key] = kwargs[key]
+                    elif key in _EXCLUSIVE_TRACEBACK_ARGUMENTS:
+                        traceback_kwargs[key] = kwargs.pop(key)
+
+            self.console = console_t(
+                highlight=False, force_terminal=True, file=s.__stdout__, **kwargs
+            )
+            self.DoEmit = self.console.print
+            self.FlushStream = self.console.file.flush
+
+            if self.should_install_traceback:
+                traceback_kwargs["console"] = self.console
+                InstallTracebackHandler(**traceback_kwargs)
+
+        def emit(self, record: l.LogRecord, /) -> None:
+            """"""
+            message = MessageFromRecord(
+                record,
+                self.page_width,
+                self.wrapping_is_disabled,
+                self.theme,
+                self.Rule,
+            )
+            self.DoEmit(message, crop=False, overflow="ignore")
+
+        def flush(self) -> None:
+            """"""
+            self.FlushStream()
+
+        def Rule(
+            self, /, *, text: str | None = None, color: str | None = None
+        ) -> str | rule_t:
+            """"""
+            if color is None:
+                color = self.theme.rule
+            if text in (None, "None"):
+                return rule_t(style=color)
+            return rule_t(title=text_t(text, style=f"bold {color}"), style=color)
+
+    def MakeThemeRich(theme: theme_t, /) -> None:
+        """"""
+        theme.SetColorizedMessageFunction(_ColorizedMessage)
+        if theme.should_alternate_background:
+            # Done here to avoid adding the Rich dependency to the theme_t implementation.
+            color = color_t.from_rgb(*COLORS_TERMINAL_256[theme.background_alt][2])
+            theme.background_alt = style_t(bgcolor=color)
+
+    def _ColorizedMessage(
+        theme: theme_t,
+        log_level: int,
+        when_or_elapsed_and_level: str,
+        message: str,
+        where_and_whatnot: str,
+        has_actual_expected: bool,
+        /,
+    ) -> text_t:
+        """"""
+        output = text_t(
+            f"{when_or_elapsed_and_level}{message}{where_and_whatnot}", theme.text
+        )
+
+        output.stylize(theme.level[log_level], end=CONTEXT_LENGTH_p_1)
+        if has_actual_expected:
+            _ = output.highlight_words(ACTUAL_PATTERNS, style=theme.actual)
+            _ = output.highlight_regex(EXPECTED_PATTERN, style=theme.expected)
+        if where_and_whatnot.__len__() > 0:
+            output.stylize(theme.where, start=CONTEXT_LENGTH_p_1 + message.__len__())
+
+        if theme.should_alternate_background:
+            if theme.should_set_background:
+                output.stylize(theme.background_alt)
+                theme.should_set_background = False
+            else:
+                theme.should_set_background = True
+
+        return output
+else:
+    from .monochrome import monochrome_handler_t as color_rich_handler_t  # noqa
+
+    s.stderr.write(MISSING_RICH_MESSAGE + "\n")

ft_logger/catalog/handler/file.py

@@ -0,0 +1,60 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+import logging as l
+from pathlib import Path as path_t
+
+from ...config.message import FALLBACK_PAGE_WIDTH
+from ...extension.object import DefaultNameFor
+from ...task.conversion.record import MessageFromRecord
+from ...type.rule import NewRule
+
+base_t = l.FileHandler
+
+
+class file_handler_t(base_t):
+    def __init__(self, *_, **kwargs) -> None:
+        """"""
+        path: str | path_t | None = kwargs.pop("path", None)
+        assert path is not None
+
+        path = path_t(path)
+        assert not path.exists()
+
+        parent = path.parent
+        if parent.exists():
+            assert parent.is_dir()
+        else:
+            parent.mkdir(mode=0o700, parents=True)
+
+        path.touch(mode=0o600, exist_ok=False)  # Only to check writability.
+
+        base_t.__init__(self, path)
+
+        self.name: str = kwargs.pop("name", DefaultNameFor(self))
+        self.page_width: int = kwargs.pop("page_width", -1)
+        self.wrapping_is_disabled = True
+        self.DoEmit = self.stream.write
+
+        self.__post_init__(kwargs.pop("level", l.INFO))
+
+    def __post_init__(self, level: int, /) -> None:
+        """"""
+        self.setLevel(level)
+
+        if 0 < self.page_width < FALLBACK_PAGE_WIDTH:
+            # Prevent message width from being "unrealistically" small.
+            self.page_width = FALLBACK_PAGE_WIDTH
+        self.wrapping_is_disabled = self.page_width <= 0
+
+    def emit(self, record: l.LogRecord, /) -> None:
+        """"""
+        self.DoEmit(
+            MessageFromRecord(
+                record, self.page_width, self.wrapping_is_disabled, None, NewRule
+            )
+            + "\n"
+        )

ft_logger/catalog/handler/generic.py

@@ -0,0 +1,125 @@
+"""
+SEE COPYRIGHT, LICENCE, and DOCUMENTATION NOTICES: files
+README-COPYRIGHT-utf8.txt, README-LICENCE-utf8.txt, and README-DOCUMENTATION-utf8.txt
+at project source root.
+"""
+
+import logging as l
+import sys as s
+import typing as h
+
+from ...catalog.config.optional import RICH_IS_AVAILABLE
+
+if RICH_IS_AVAILABLE:
+    from rich.console import Console as console_t
+    from rich.rule import Rule as rule_t
+    from rich.terminal_theme import DEFAULT_TERMINAL_THEME
+    from rich.text import Text as text_t
+
+    from .color_rich import MakeThemeRich
+else:
+    console_t = rule_t = DEFAULT_TERMINAL_THEME = text_t = None
+
+from ...config.message import FALLBACK_PAGE_WIDTH
+from ...extension.object import DefaultNameFor
+from ...task.conversion.record import MessageFromRecord
+from ...type.rule import NewRule
+from ...type.theme import theme_t
+
+base_t = l.Handler
+
+
+class generic_handler_t(base_t):
+    """
+    EmitMessage (h.Callable): Some callables may induce infinite loops if the logger
+        intercepts "print" calls, e.g. print, s.stdout.write, s.stderr.write.
+    """
+    def __init__(self, *_, **kwargs) -> None:
+        """"""
+        base_t.__init__(self)
+
+        self.name: str = kwargs.pop("name", DefaultNameFor(self))
+        self.page_width: int = kwargs.pop("page_width", -1)
+        self.wrapping_is_disabled = True
+        self.supports_html = False
+        self.theme: str | theme_t | None = kwargs.pop("theme", None)
+        self.console = None  # console_t | None.
+        self.console_options = None  # rich.console.ConsoleOptions | None.
+        self.DoEmit: h.Callable | None = kwargs.pop("EmitMessage", None)
+
+        self.__post_init__(
+            kwargs.pop("level", l.INFO), kwargs.pop("supports_html", False)
+        )
+
+    def __post_init__(self, level: int, supports_html: bool, /) -> None:
+        """"""
+        # print, s.stdout.write, s.stderr.write: Basic prevention against infinite loop.
+        # See class documentation.
+        assert self.DoEmit not in (None, print, s.stdout.write, s.stderr.write)
+
+        self.setLevel(level)
+
+        if 0 < self.page_width < FALLBACK_PAGE_WIDTH:
+            # Prevent message width from being "unrealistically" small.
+            self.page_width = FALLBACK_PAGE_WIDTH
+        self.wrapping_is_disabled = self.page_width <= 0
+
+        if supports_html and (console_t is not None):
+            self.supports_html = True
+            self.console = console_t(highlight=False, force_terminal=True)
+            self.console_options = self.console.options.update(
+                overflow="ignore", no_wrap=True
+            )
+
+            if self.theme is None:
+                self.theme = theme_t.NewDefault("rich", "light")
+            elif isinstance(self.theme, str):
+                self.theme = theme_t.NewDefaultFromStr(self.theme)
+            MakeThemeRich(self.theme)
+
+    def Rule(
+        self, /, *, text: str | None = None, color: str | None = None
+    ) -> str | rule_t:
+        """"""
+        if (color is None) and (self.theme is not None):
+            color = self.theme.rule
+
+        if self.supports_html:
+            if text in (None, "None"):
+                return rule_t(style=color)
+            return rule_t(title=text_t(text, style=f"bold {color}"), style=color)
+
+        return NewRule(text=text, color=color)
+
+    def emit(self, record: l.LogRecord, /) -> None:
+        """"""
+        message = MessageFromRecord(
+            record, self.page_width, self.wrapping_is_disabled, self.theme, self.Rule
+        )
+
+        if self.supports_html:
+            segments = self.console.render(message, options=self.console_options)
+
+            # Inspired from the code of: rich.console.export_html.
+            html_segments = []
+            for text, style, _ in segments:
+                if text == "\n":
+                    html_segments.append("\n")
+                else:
+                    if style is not None:
+                        style = style.get_html_style(DEFAULT_TERMINAL_THEME)
+                        if (style is not None) and (style.__len__() > 0):
+                            text = f'<span style="{style};">{text}</span>'
+                    html_segments.append(text)
+            if html_segments[-1] == "\n":
+                html_segments = html_segments[:-1]
+
+            # /!\ For some reason, the widget splits the message into lines, place each
+            # line inside a pre tag, and set margin-bottom of the first and list lines
+            # to 12px. This can be seen by printing self.contents.toHtml(). To avoid the
+            # unwanted extra margins, margin-bottom is set to 0 below.
+            message = (
+                "<pre style='margin-bottom:0px'>" + "".join(html_segments) + "</pre>"
+            )
+
+        self.DoEmit(message)