omlish 0.0.0.dev423__py3-none-any.whl → 0.0.0.dev484__py3-none-any.whl

omlish/logs/infos.py

@@ -0,0 +1,377 @@
+# ruff: noqa: UP006 UP007 UP045
+# @omlish-lite
+"""
+TODO:
+ - remove redundant info fields only present for std adaptation (Level.name, ...)
+"""
+import collections.abc
+import io
+import logging
+import os.path
+import sys
+import threading
+import time
+import traceback
+import types
+import typing as ta
+
+from .levels import NamedLogLevel
+from .warnings import LoggingSetupWarning
+
+
+LoggingMsgFn = ta.Callable[[], ta.Union[str, tuple]]  # ta.TypeAlias
+
+LoggingExcInfoTuple = ta.Tuple[ta.Type[BaseException], BaseException, ta.Optional[types.TracebackType]]  # ta.TypeAlias
+LoggingExcInfo = ta.Union[BaseException, LoggingExcInfoTuple]  # ta.TypeAlias
+LoggingExcInfoArg = ta.Union[LoggingExcInfo, bool, None]  # ta.TypeAlias
+
+LoggingContextInfo = ta.Any  # ta.TypeAlias
+
+
+##
+
+
+def logging_context_info(cls):
+    return cls
+
+
+@ta.final
+class LoggingContextInfos:
+    def __new__(cls, *args, **kwargs):  # noqa
+        raise TypeError
+
+    #
+
+    @logging_context_info
+    @ta.final
+    class Name(ta.NamedTuple):
+        name: str
+
+    @logging_context_info
+    @ta.final
+    class Level(ta.NamedTuple):
+        level: NamedLogLevel
+        name: str
+
+        @classmethod
+        def build(cls, level: int) -> 'LoggingContextInfos.Level':
+            nl: NamedLogLevel = level if level.__class__ is NamedLogLevel else NamedLogLevel(level)  # type: ignore[assignment]  # noqa
+            return cls(
+                level=nl,
+                name=logging.getLevelName(nl),
+            )
+
+    @logging_context_info
+    @ta.final
+    class Msg(ta.NamedTuple):
+        msg: str
+        args: ta.Union[tuple, ta.Mapping[ta.Any, ta.Any], None]
+
+        @classmethod
+        def build(
+                cls,
+                msg: ta.Union[str, tuple, LoggingMsgFn],
+                *args: ta.Any,
+        ) -> 'LoggingContextInfos.Msg':
+            s: str
+            a: ta.Any
+
+            if callable(msg):
+                if args:
+                    raise TypeError(f'Must not provide both a message function and args: {msg=} {args=}')
+                x = msg()
+                if isinstance(x, str):
+                    s, a = x, ()
+                elif isinstance(x, tuple):
+                    if x:
+                        s, a = x[0], x[1:]
+                    else:
+                        s, a = '', ()
+                else:
+                    raise TypeError(x)
+
+            elif isinstance(msg, tuple):
+                if args:
+                    raise TypeError(f'Must not provide both a tuple message and args: {msg=} {args=}')
+                if msg:
+                    s, a = msg[0], msg[1:]
+                else:
+                    s, a = '', ()
+
+            elif isinstance(msg, str):
+                s, a = msg, args
+
+            else:
+                raise TypeError(msg)
+
+            # https://github.com/python/cpython/blob/e709361fc87d0d9ab9c58033a0a7f2fef0ad43d2/Lib/logging/__init__.py#L307  # noqa
+            if a and len(a) == 1 and isinstance(a[0], collections.abc.Mapping) and a[0]:
+                a = a[0]
+
+            return cls(
+                msg=s,
+                args=a,
+            )
+
+    @logging_context_info
+    @ta.final
+    class Extra(ta.NamedTuple):
+        extra: ta.Mapping[ta.Any, ta.Any]
+
+    @logging_context_info
+    @ta.final
+    class Time(ta.NamedTuple):
+        ns: int
+        secs: float
+        msecs: float
+        relative_secs: float
+
+        @classmethod
+        def get_std_start_ns(cls) -> int:
+            x: ta.Any = logging._startTime  # type: ignore[attr-defined]  # noqa
+
+            # Before 3.13.0b1 this will be `time.time()`, a float of seconds. After that, it will be `time.time_ns()`,
+            # an int.
+            #
+            # See:
+            #  - https://github.com/python/cpython/commit/1316692e8c7c1e1f3b6639e51804f9db5ed892ea
+            #
+            if isinstance(x, float):
+                return int(x * 1e9)
+            else:
+                return x
+
+        @classmethod
+        def build(
+                cls,
+                ns: int,
+                *,
+                start_ns: ta.Optional[int] = None,
+        ) -> 'LoggingContextInfos.Time':
+            # https://github.com/python/cpython/commit/1316692e8c7c1e1f3b6639e51804f9db5ed892ea
+            secs = ns / 1e9  # ns to float seconds
+
+            # Get the number of whole milliseconds (0-999) in the fractional part of seconds.
+            # Eg: 1_677_903_920_999_998_503 ns --> 999_998_503 ns--> 999 ms
+            # Convert to float by adding 0.0 for historical reasons. See gh-89047
+            msecs = (ns % 1_000_000_000) // 1_000_000 + 0.0
+
+            # https://github.com/python/cpython/commit/1500a23f33f5a6d052ff1ef6383d9839928b8ff1
+            if msecs == 999.0 and int(secs) != ns // 1_000_000_000:
+                # ns -> sec conversion can round up, e.g:
+                # 1_677_903_920_999_999_900 ns --> 1_677_903_921.0 sec
+                msecs = 0.0
+
+            if start_ns is None:
+                start_ns = cls.get_std_start_ns()
+            relative_secs = (ns - start_ns) / 1e6
+
+            return cls(
+                ns=ns,
+                secs=secs,
+                msecs=msecs,
+                relative_secs=relative_secs,
+            )
+
+    @logging_context_info
+    @ta.final
+    class Exc(ta.NamedTuple):
+        info: LoggingExcInfo
+        info_tuple: LoggingExcInfoTuple
+
+        @classmethod
+        def build(
+                cls,
+                arg: LoggingExcInfoArg = False,
+        ) -> ta.Optional['LoggingContextInfos.Exc']:
+            if arg is True:
+                sys_exc_info = sys.exc_info()
+                if sys_exc_info[0] is not None:
+                    arg = sys_exc_info
+                else:
+                    arg = None
+            elif arg is False:
+                arg = None
+            if arg is None:
+                return None
+
+            info: LoggingExcInfo = arg
+            if isinstance(info, BaseException):
+                info_tuple: LoggingExcInfoTuple = (type(info), info, info.__traceback__)  # noqa
+            else:
+                info_tuple = info
+
+            return cls(
+                info=info,
+                info_tuple=info_tuple,
+            )
+
+    @logging_context_info
+    @ta.final
+    class Caller(ta.NamedTuple):
+        file_path: str
+        line_no: int
+        func_name: str
+        stack_info: ta.Optional[str]
+
+        @classmethod
+        def is_internal_frame(cls, frame: types.FrameType) -> bool:
+            file_path = os.path.normcase(frame.f_code.co_filename)
+
+            # Yes, really.
+            # https://github.com/python/cpython/blob/e709361fc87d0d9ab9c58033a0a7f2fef0ad43d2/Lib/logging/__init__.py#L204  # noqa
+            # https://github.com/python/cpython/commit/5ca6d7469be53960843df39bb900e9c3359f127f
+            if 'importlib' in file_path and '_bootstrap' in file_path:
+                return True
+
+            return False
+
+        @classmethod
+        def find_frame(cls, stack_offset: int = 0) -> ta.Optional[types.FrameType]:
+            f: ta.Optional[types.FrameType] = sys._getframe(2 + stack_offset)  # noqa
+
+            while f is not None:
+                # NOTE: We don't check __file__ like stdlib since we may be running amalgamated - we rely on careful,
+                # manual stack_offset management.
+                if hasattr(f, 'f_code'):
+                    return f
+
+                f = f.f_back
+
+            return None
+
+        @classmethod
+        def build(
+                cls,
+                stack_offset: int = 0,
+                *,
+                stack_info: bool = False,
+        ) -> ta.Optional['LoggingContextInfos.Caller']:
+            if (f := cls.find_frame(stack_offset + 1)) is None:
+                return None
+
+            # https://github.com/python/cpython/blob/08e9794517063c8cd92c48714071b1d3c60b71bd/Lib/logging/__init__.py#L1616-L1623  # noqa
+            sinfo = None
+            if stack_info:
+                sio = io.StringIO()
+                traceback.print_stack(f, file=sio)
+                sinfo = sio.getvalue()
+                sio.close()
+                if sinfo[-1] == '\n':
+                    sinfo = sinfo[:-1]
+
+            return cls(
+                file_path=f.f_code.co_filename,
+                line_no=f.f_lineno or 0,
+                func_name=f.f_code.co_name,
+                stack_info=sinfo,
+            )
+
+    @logging_context_info
+    @ta.final
+    class SourceFile(ta.NamedTuple):
+        file_name: str
+        module: str
+
+        @classmethod
+        def build(cls, caller_file_path: ta.Optional[str]) -> ta.Optional['LoggingContextInfos.SourceFile']:
+            if caller_file_path is None:
+                return None
+
+            # https://github.com/python/cpython/blob/e709361fc87d0d9ab9c58033a0a7f2fef0ad43d2/Lib/logging/__init__.py#L331-L336  # noqa
+            try:
+                file_name = os.path.basename(caller_file_path)
+                module = os.path.splitext(file_name)[0]
+            except (TypeError, ValueError, AttributeError):
+                return None
+
+            return cls(
+                file_name=file_name,
+                module=module,
+            )
+
+    @logging_context_info
+    @ta.final
+    class Thread(ta.NamedTuple):
+        ident: int
+        native_id: ta.Optional[int]
+        name: str
+
+        @classmethod
+        def build(cls) -> 'LoggingContextInfos.Thread':
+            return cls(
+                ident=threading.get_ident(),
+                native_id=threading.get_native_id() if hasattr(threading, 'get_native_id') else None,
+                name=threading.current_thread().name,
+            )
+
+    @logging_context_info
+    @ta.final
+    class Process(ta.NamedTuple):
+        pid: int
+
+        @classmethod
+        def build(cls) -> 'LoggingContextInfos.Process':
+            return cls(
+                pid=os.getpid(),
+            )
+
+    @logging_context_info
+    @ta.final
+    class Multiprocessing(ta.NamedTuple):
+        process_name: str
+
+        @classmethod
+        def build(cls) -> ta.Optional['LoggingContextInfos.Multiprocessing']:
+            # https://github.com/python/cpython/blob/e709361fc87d0d9ab9c58033a0a7f2fef0ad43d2/Lib/logging/__init__.py#L355-L364  # noqa
+            if (mp := sys.modules.get('multiprocessing')) is None:
+                return None
+
+            return cls(
+                process_name=mp.current_process().name,
+            )
+
+    @logging_context_info
+    @ta.final
+    class AsyncioTask(ta.NamedTuple):
+        name: str
+
+        @classmethod
+        def build(cls) -> ta.Optional['LoggingContextInfos.AsyncioTask']:
+            # https://github.com/python/cpython/blob/e709361fc87d0d9ab9c58033a0a7f2fef0ad43d2/Lib/logging/__init__.py#L372-L377  # noqa
+            if (asyncio := sys.modules.get('asyncio')) is None:
+                return None
+
+            try:
+                task = asyncio.current_task()
+            except Exception:  # noqa
+                return None
+
+            if task is None:
+                return None
+
+            return cls(
+                name=task.get_name(),  # Always non-None
+            )
+
+
+##
+
+
+class UnexpectedLoggingStartTimeWarning(LoggingSetupWarning):
+    pass
+
+
+def _check_logging_start_time() -> None:
+    if (x := LoggingContextInfos.Time.get_std_start_ns()) < (t := time.time()):
+        import warnings  # noqa
+
+        warnings.warn(
+            f'Unexpected logging start time detected: '
+            f'get_std_start_ns={x}, '
+            f'time.time()={t}',
+            UnexpectedLoggingStartTimeWarning,
+        )
+
+
+_check_logging_start_time()

omlish/logs/levels.py

@@ -1,7 +1,104 @@
+# ruff: noqa: UP006 UP045
 # @omlish-lite
+import logging
+import typing as ta
 
 
 LogLevel = int  # ta.TypeAlias
 
 
 ##
+
+
+@ta.final
+class NamedLogLevel(int):
+    # logging.getLevelNamesMapping (or, as that is unavailable <3.11, logging._nameToLevel) includes the deprecated
+    # aliases.
+    _NAMES_BY_INT: ta.ClassVar[ta.Mapping[LogLevel, str]] = dict(sorted(logging._levelToName.items(), key=lambda t: -t[0]))  # noqa
+
+    _INTS_BY_NAME: ta.ClassVar[ta.Mapping[str, LogLevel]] = {v: k for k, v in _NAMES_BY_INT.items()}
+
+    _NAME_INT_PAIRS: ta.ClassVar[ta.Sequence[ta.Tuple[str, LogLevel]]] = list(_INTS_BY_NAME.items())
+
+    #
+
+    _CACHE: ta.ClassVar[ta.MutableMapping[int, 'NamedLogLevel']] = {}
+
+    @ta.overload
+    def __new__(cls, name: str, offset: int = 0, /) -> 'NamedLogLevel':
+        ...
+
+    @ta.overload
+    def __new__(cls, i: int, /) -> 'NamedLogLevel':
+        ...
+
+    def __new__(cls, x, offset=0, /):
+        if isinstance(x, str):
+            return cls(cls._INTS_BY_NAME[x.upper()] + offset)
+        elif not offset and (c := cls._CACHE.get(x)) is not None:
+            return c
+        else:
+            return super().__new__(cls, x + offset)
+
+    #
+
+    _name_and_offset: ta.Tuple[str, int]
+
+    @property
+    def name_and_offset(self) -> ta.Tuple[str, int]:
+        try:
+            return self._name_and_offset
+        except AttributeError:
+            pass
+
+        if (n := self._NAMES_BY_INT.get(self)) is not None:
+            t = (n, 0)
+        else:
+            for n, i in self._NAME_INT_PAIRS:  # noqa
+                if self >= i:
+                    t = (n, (self - i))
+                    break
+            else:
+                t = ('NOTSET', int(self))
+
+        self._name_and_offset = t
+        return t
+
+    @property
+    def exact_name(self) -> ta.Optional[str]:
+        n, o = self.name_and_offset
+        return n if not o else None
+
+    @property
+    def effective_name(self) -> str:
+        n, _ = self.name_and_offset
+        return n
+
+    #
+
+    def __str__(self) -> str:
+        return self.exact_name or f'{self.effective_name}{int(self):+}'
+
+    def __repr__(self) -> str:
+        n, o = self.name_and_offset
+        return f'{self.__class__.__name__}({n!r}{f", {int(o)}" if o else ""})'
+
+    #
+
+    CRITICAL: ta.ClassVar['NamedLogLevel']
+    ERROR: ta.ClassVar['NamedLogLevel']
+    WARNING: ta.ClassVar['NamedLogLevel']
+    INFO: ta.ClassVar['NamedLogLevel']
+    DEBUG: ta.ClassVar['NamedLogLevel']
+    NOTSET: ta.ClassVar['NamedLogLevel']
+
+
+NamedLogLevel.CRITICAL = NamedLogLevel(logging.CRITICAL)
+NamedLogLevel.ERROR = NamedLogLevel(logging.ERROR)
+NamedLogLevel.WARNING = NamedLogLevel(logging.WARNING)
+NamedLogLevel.INFO = NamedLogLevel(logging.INFO)
+NamedLogLevel.DEBUG = NamedLogLevel(logging.DEBUG)
+NamedLogLevel.NOTSET = NamedLogLevel(logging.NOTSET)
+
+
+NamedLogLevel._CACHE.update({i: NamedLogLevel(i) for i in NamedLogLevel._NAMES_BY_INT})  # noqa

omlish/logs/modules.py

@@ -0,0 +1,13 @@
+# @omlish-lite
+import logging
+import typing as ta
+
+from .base import Logger
+from .std.loggers import StdLogger
+
+
+##
+
+
+def get_module_logger(mod_globals: ta.Mapping[str, ta.Any]) -> Logger:
+    return StdLogger(logging.getLogger(mod_globals.get('__name__')))  # noqa

omlish/logs/protocols.py

@@ -0,0 +1,32 @@
+# @omlish-lite
+import typing as ta
+
+from .levels import LogLevel
+
+
+##
+
+
+@ta.runtime_checkable
+class LoggerLike(ta.Protocol):
+    """Satisfied by both our Logger and stdlib logging.Logger."""
+
+    def isEnabledFor(self, level: LogLevel) -> bool: ...  # noqa
+
+    def getEffectiveLevel(self) -> LogLevel: ...  # noqa
+
+    #
+
+    def log(self, level: LogLevel, msg: str, /, *args: ta.Any, **kwargs: ta.Any) -> None: ...  # noqa
+
+    def debug(self, msg: str, /, *args: ta.Any, **kwargs: ta.Any) -> None: ...  # noqa
+
+    def info(self, msg: str, /, *args: ta.Any, **kwargs: ta.Any) -> None: ...  # noqa
+
+    def warning(self, msg: str, /, *args: ta.Any, **kwargs: ta.Any) -> None: ...  # noqa
+
+    def error(self, msg: str, /, *args: ta.Any, **kwargs: ta.Any) -> None: ...  # noqa
+
+    def exception(self, msg: str, /, *args: ta.Any, **kwargs: ta.Any) -> None: ...  # noqa
+
+    def critical(self, msg: str, /, *args: ta.Any, **kwargs: ta.Any) -> None: ...  # noqa

omlish/logs/standard.py

@@ -2,6 +2,7 @@
 # @omlish-lite
 """
 TODO:
+ - !! move to std !!
  - structured
  - prefixed
  - debug
@@ -12,9 +13,9 @@ import datetime
 import logging
 import typing as ta
 
-from .filters import TidLogFilter
-from .json import JsonLogFormatter
-from .proxy import ProxyLogHandler
+from .std.filters import TidLoggingFilter
+from .std.json import JsonLoggingFormatter
+from .std.proxy import ProxyLoggingHandler
 
 
 ##
@@ -31,7 +32,7 @@ STANDARD_LOG_FORMAT_PARTS = [
 ]
 
 
-class StandardLogFormatter(logging.Formatter):
+class StandardLoggingFormatter(logging.Formatter):
     @staticmethod
     def build_log_format(parts: ta.Iterable[ta.Tuple[str, str]]) -> str:
         return ' '.join(v for k, v in parts)
@@ -50,7 +51,7 @@ class StandardLogFormatter(logging.Formatter):
 ##
 
 
-class StandardConfiguredLogHandler(ProxyLogHandler):
+class StandardConfiguredLoggingHandler(ProxyLoggingHandler):
     def __init_subclass__(cls, **kwargs):
         raise TypeError('This class serves only as a marker and should not be subclassed.')
 
@@ -79,11 +80,15 @@ def _locking_logging_module_lock() -> ta.Iterator[None]:
 def configure_standard_logging(
         level: ta.Union[int, str] = logging.INFO,
         *,
-        json: bool = False,
         target: ta.Optional[logging.Logger] = None,
+
         force: bool = False,
+
         handler_factory: ta.Optional[ta.Callable[[], logging.Handler]] = None,
-) -> ta.Optional[StandardConfiguredLogHandler]:
+
+        formatter: ta.Optional[logging.Formatter] = None,  # noqa
+        json: bool = False,
+) -> ta.Optional[StandardConfiguredLoggingHandler]:
     with _locking_logging_module_lock():
         if target is None:
             target = logging.root
@@ -91,7 +96,7 @@ def configure_standard_logging(
         #
 
         if not force:
-            if any(isinstance(h, StandardConfiguredLogHandler) for h in list(target.handlers)):
+            if any(isinstance(h, StandardConfiguredLoggingHandler) for h in list(target.handlers)):
                 return None
 
         #
@@ -103,16 +108,16 @@ def configure_standard_logging(
 
         #
 
-        formatter: logging.Formatter
-        if json:
-            formatter = JsonLogFormatter()
-        else:
-            formatter = StandardLogFormatter(StandardLogFormatter.build_log_format(STANDARD_LOG_FORMAT_PARTS))
+        if formatter is None:
+            if json:
+                formatter = JsonLoggingFormatter()
+            else:
+                formatter = StandardLoggingFormatter(StandardLoggingFormatter.build_log_format(STANDARD_LOG_FORMAT_PARTS))  # noqa
         handler.setFormatter(formatter)
 
         #
 
-        handler.addFilter(TidLogFilter())
+        handler.addFilter(TidLoggingFilter())
 
         #
 
@@ -125,4 +130,4 @@ def configure_standard_logging(
 
         #
 
-        return StandardConfiguredLogHandler(handler)
+        return StandardConfiguredLoggingHandler(handler)

omlish/logs/std/configs.py

@@ -0,0 +1,29 @@
+# ruff: noqa: UP006 UP045
+# @omlish-lite
+"""
+https://docs.python.org/3/howto/logging.html#configuring-logging
+https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
+"""
+import dataclasses as dc
+import typing as ta
+
+
+FilterDictLoggingConfig = ta.Dict[str, ta.Any]  # ta.TypeAlias
+FormatterDictLoggingConfig = ta.Dict[str, ta.Any]  # ta.TypeAlias
+HandlerDictLoggingConfig = ta.Dict[str, ta.Any]  # ta.TypeAlias
+LoggerDictLoggingConfig = ta.Dict[str, ta.Any]  # ta.TypeAlias
+
+
+##
+
+
+@dc.dataclass()
+class DictLoggingConfig:
+    version: int = 1
+    incremental: bool = False
+    disable_existing_loggers: bool = False
+    filters: ta.Dict[str, FilterDictLoggingConfig] = dc.field(default_factory=dict)
+    formatters: ta.Dict[str, FormatterDictLoggingConfig] = dc.field(default_factory=dict)
+    handlers: ta.Dict[str, HandlerDictLoggingConfig] = dc.field(default_factory=dict)
+    loggers: ta.Dict[str, LoggerDictLoggingConfig] = dc.field(default_factory=dict)
+    root: ta.Optional[LoggerDictLoggingConfig] = None

omlish/logs/{filters.py → std/filters.py}

@@ -7,7 +7,7 @@ import threading
 ##
 
 
-class TidLogFilter(logging.Filter):
+class TidLoggingFilter(logging.Filter):
     def filter(self, record):
         # FIXME: handle better - missing from wasm and cosmos
         if hasattr(threading, 'get_native_id'):

omlish/logs/std/formatters.py

@@ -0,0 +1,25 @@
+import logging
+import typing as ta
+
+from ..formatters import LoggingContextFormatter
+from .records import LoggingContextLogRecord
+from .records import LogRecordLoggingContext
+
+
+##
+
+
+@ta.final
+class StdLoggingFormatter(logging.Formatter):
+    def __init__(self, ctx_formatter: LoggingContextFormatter) -> None:
+        super().__init__()
+
+        self._ctx_formatter = ctx_formatter
+
+    def format(self, rec: logging.LogRecord) -> str:
+        if isinstance(rec, LoggingContextLogRecord):
+            ctx = rec._logging_context  # noqa
+        else:
+            ctx = LogRecordLoggingContext(rec)
+
+        return self._ctx_formatter.format(ctx)