thds.core 0.0.1__py3-none-any.whl → 1.31.20250123022540__py3-none-any.whl

thds/core/log/logfmt.py

@@ -0,0 +1,302 @@
+# MIT License
+
+# Copyright (c) 2022 Joshua Taylor Eppinette
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# flake8: noqa
+
+import io
+import logging
+import numbers
+import traceback
+from contextlib import closing
+from types import TracebackType
+from typing import Dict, List, Optional, Tuple, Type, cast
+
+ExcInfo = Tuple[Type[BaseException], BaseException, TracebackType]
+
+# Reserved log record attributes cannot be overwritten. They
+# will not be included in the formatted log.
+#
+# https://docs.python.org/3/library/logging.html#logrecord-attributes
+RESERVED: Tuple[str, ...] = (
+    "args",
+    "asctime",
+    "created",
+    "exc_info",
+    "exc_text",
+    "filename",
+    "funcName",
+    "levelname",
+    "levelno",
+    "lineno",
+    "message",
+    "module",
+    "msecs",
+    "msg",
+    "name",
+    "pathname",
+    "process",
+    "processName",
+    "relativeCreated",
+    "stack_info",
+    "taskName",
+    "thread",
+    "threadName",
+)
+
+
+class Logfmter(logging.Formatter):
+    @classmethod
+    def format_string(cls, value: str) -> str:
+        """
+        Process the provided string with any necessary quoting and/or escaping.
+        """
+        needs_dquote_escaping = '"' in value
+        needs_newline_escaping = "\n" in value
+        needs_quoting = " " in value or "=" in value
+
+        if needs_dquote_escaping:
+            value = value.replace('"', '\\"')
+
+        if needs_newline_escaping:
+            value = value.replace("\n", "\\n")
+
+        if needs_quoting:
+            value = '"{}"'.format(value)
+
+        return value if value else '""'
+
+    @classmethod
+    def format_value(cls, value) -> str:
+        """
+        Map the provided value to the proper logfmt formatted string.
+        """
+        if value is None:
+            return ""
+        elif isinstance(value, bool):
+            return "true" if value else "false"
+        elif isinstance(value, numbers.Number):
+            return str(value)
+
+        return cls.format_string(str(value))
+
+    @classmethod
+    def format_exc_info(cls, exc_info: ExcInfo) -> str:
+        """
+        Format the provided exc_info into a logfmt formatted string.
+
+        This function should only be used to format exceptions which are
+        currently being handled. Not with those exceptions which are
+        manually passed into the logger. For example:
+
+            try:
+                raise Exception()
+            except Exception:
+                logging.exception()
+        """
+        _type, exc, tb = exc_info
+
+        with closing(io.StringIO()) as sio:
+            traceback.print_exception(_type, exc, tb, None, sio)
+            value = sio.getvalue()
+
+        # Tracebacks have a single trailing newline that we don't need.
+        value = value.rstrip("\n")
+
+        return cls.format_string(value)
+
+    @classmethod
+    def format_params(cls, params: dict) -> str:
+        """
+        Return a string representing the logfmt formatted parameters.
+        """
+        return " ".join(["{}={}".format(key, cls.format_value(value)) for key, value in params.items()])
+
+    @classmethod
+    def normalize_key(cls, key: str) -> str:
+        """
+        Return a string whereby any spaces are converted to underscores and
+        newlines are escaped.
+
+        If the provided key is empty, then return a single underscore. This
+        function is used to prevent any logfmt parameters from having invalid keys.
+
+        As a choice of implementation, we normalize any keys instead of raising an
+        exception to prevent raising exceptions during logging. The goal is to never
+        impede logging. This is especially important when logging in exception handlers.
+        """
+        if not key:
+            return "_"
+
+        return key.replace(" ", "_").replace("\n", "\\n")
+
+    @classmethod
+    def get_extra(cls, record: logging.LogRecord) -> dict:
+        """
+        Return a dictionary of logger extra parameters by filtering any reserved keys.
+        """
+        return {
+            cls.normalize_key(key): value
+            for key, value in record.__dict__.items()
+            if key not in RESERVED
+        }
+
+    def __init__(
+        self,
+        keys: List[str] = ["at"],
+        mapping: Dict[str, str] = {"at": "levelname"},
+        datefmt: Optional[str] = None,
+    ):
+        self.keys = [self.normalize_key(key) for key in keys]
+        self.mapping = {self.normalize_key(key): value for key, value in mapping.items()}
+        self.datefmt = datefmt
+
+    def format_key_value(self, record: logging.LogRecord, key: str, value) -> str:
+        """This is net-new code that makes the formatter more extensible."""
+        return f"{key}={self.format_value(value)}"
+
+    def format(self, record: logging.LogRecord) -> str:
+        # If the 'asctime' attribute will be used, then generate it.
+        if "asctime" in self.keys or "asctime" in self.mapping.values():
+            record.asctime = self.formatTime(record, self.datefmt)
+
+        if isinstance(record.msg, dict):
+            params = {self.normalize_key(key): value for key, value in record.msg.items()}
+        else:
+            params = {"msg": record.getMessage()}
+
+        params.update(self.get_extra(record))
+
+        tokens = []
+
+        # Add the initial tokens from the provided list of default keys.
+        #
+        # This supports parameters which should be included in every log message. The
+        # values for these keys must already exist on the log record. If they are
+        # available under a different attribute name, then the formatter's mapping will
+        # be used to lookup these attributes. e.g. 'at' from 'levelname'
+        for key in self.keys:
+
+            attribute = key
+
+            # If there is a mapping for this key's attribute, then use it to lookup
+            # the key's value.
+            if key in self.mapping:
+                attribute = self.mapping[key]
+
+            # If this key is in params, then skip it, because it was manually passed in
+            # will be added via the params system.
+            if attribute in params:
+                continue
+
+            # If the attribute doesn't exist on the log record, then skip it.
+            if not hasattr(record, attribute):
+                continue
+
+            value = getattr(record, attribute)
+
+            tokens.append(self.format_key_value(record, key, value))
+
+        formatted_params = self.format_params(params)
+        if formatted_params:
+            tokens.append(formatted_params)
+
+        if record.exc_info:
+            # Cast exc_info to its not null variant to make mypy happy.
+            exc_info = cast(ExcInfo, record.exc_info)
+
+            tokens.append("exc_info={}".format(self.format_exc_info(exc_info)))
+
+        return " ".join(tokens)
+
+
+# all of the above is _almost_ identical (minus format_key_value) to the raw source from
+# https://github.com/jteppinette/python-logfmter
+#
+# what follows is our slight modifications
+
+from .. import ansi_esc
+from .kw_formatter import ThdsCompactFormatter
+from .kw_logger import TH_REC_CTXT
+
+# similar to what's in kw_formatter, but does not use background colors
+# since those don't seem to translate well in k8s/Grafana:
+_COLOR_LEVEL_MAP = {
+    "low": f"{ansi_esc.fg.BLUE}{{}}{ansi_esc.fg.RESET}",
+    "info": f"{ansi_esc.fg.GREEN}{{}}{ansi_esc.fg.RESET}",
+    "warning": (
+        f"{ansi_esc.fg.YELLOW}{ansi_esc.style.BRIGHT}" "{}" f"{ansi_esc.style.NORMAL}{ansi_esc.fg.RESET}"
+    ),
+    "error": (
+        f"{ansi_esc.fg.RED}{ansi_esc.style.BRIGHT}" "{}" f"{ansi_esc.style.NORMAL}{ansi_esc.fg.RESET}"
+    ),
+    "critical": (
+        f"{ansi_esc.fg.MAGENTA}{ansi_esc.style.BRIGHT}"
+        "{}"
+        f"{ansi_esc.fg.RESET}{ansi_esc.style.NORMAL}"
+    ),
+}
+
+
+def log_level_caps(levelno: int, levelname: str) -> str:
+    if levelno < logging.WARNING:
+        return levelname.lower()
+    return levelname
+
+
+def log_level_color(levelno: int, base_levelname: str) -> str:
+    if levelno < logging.INFO:
+        return _COLOR_LEVEL_MAP["low"].format(base_levelname)
+    elif levelno < logging.WARNING:
+        return _COLOR_LEVEL_MAP["info"].format(base_levelname)
+    elif levelno < logging.ERROR:
+        return _COLOR_LEVEL_MAP["warning"].format(base_levelname)
+    elif levelno < logging.CRITICAL:
+        return _COLOR_LEVEL_MAP["error"].format(base_levelname)
+    return _COLOR_LEVEL_MAP["critical"].format(base_levelname)
+
+
+class ThdsLogfmter(Logfmter):
+    @classmethod
+    def get_extra(cls, record: logging.LogRecord) -> dict:
+        """
+        Return a dictionary of logger extra parameters by filtering any reserved keys.
+        """
+        extra = dict(super().get_extra(record))
+        th_ctx = extra.pop(TH_REC_CTXT, None)
+        if th_ctx:
+            extra.update(th_ctx)
+        return extra
+
+    def format_key_value(self, record: logging.LogRecord, key: str, value) -> str:
+        if key == "mod":
+            return f"mod={ThdsCompactFormatter.format_module_name(value)}"
+        if key == "lvl":
+            core_str = log_level_color(record.levelno, f"lvl={log_level_caps(record.levelno, value)}")
+            return core_str + " " * (7 - len(record.levelname))
+        return super().format_key_value(record, key, value)
+
+
+def mk_default_logfmter() -> ThdsLogfmter:
+    return ThdsLogfmter(
+        keys=["lvl", "mod"],
+        mapping={"lvl": "levelname", "mod": "name"},
+    )

thds/core/merge_args.py

@@ -0,0 +1,168 @@
+# Merge signatures of two functions with Advanced Hackery.
+# Copyright © 2018-2023, Chris Warrick.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions, and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions, and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the author of this software nor the names of
+#    contributors to this software may be used to endorse or promote
+#    products derived from this software without specific prior written
+#    consent.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+import functools
+import inspect
+import itertools
+import sys
+import types
+
+PY38 = sys.version_info >= (3, 8)
+PY310 = sys.version_info >= (3, 10)
+PY311 = sys.version_info >= (3, 11)
+
+
+def _blank():  # pragma: no cover
+    pass
+
+
+def _merge(source, dest):  # noqa: C901
+    """Merge the signatures of ``source`` and ``dest``.
+    ``dest`` args go before ``source`` args in all three categories
+    (positional, keyword-maybe, keyword-only).
+    """
+    source_spec = inspect.getfullargspec(source)
+    dest_spec = inspect.getfullargspec(dest)
+
+    if source_spec.varargs or source_spec.varkw:
+        raise ValueError("The source function may not take variable arguments.")
+
+    source_all = source_spec.args
+    dest_all = dest_spec.args
+
+    if source_spec.defaults:
+        source_pos = source_all[: -len(source_spec.defaults)]
+        source_kw = source_all[-len(source_spec.defaults) :]
+    else:
+        source_pos = source_all
+        source_kw = []
+
+    if dest_spec.defaults:
+        dest_pos = dest_all[: -len(dest_spec.defaults)]
+        dest_kw = dest_all[-len(dest_spec.defaults) :]
+    else:
+        dest_pos = dest_all
+        dest_kw = []
+
+    args_merged = dest_pos
+    for a in source_pos:
+        if a not in args_merged:
+            args_merged.append(a)
+
+    defaults_merged = []
+    for a, default in itertools.chain(
+        zip(dest_kw, dest_spec.defaults or []), zip(source_kw, source_spec.defaults or [])
+    ):
+        if a not in args_merged:
+            args_merged.append(a)
+            defaults_merged.append(default)
+
+    kwonlyargs_merged = dest_spec.kwonlyargs
+    for a in source_spec.kwonlyargs:
+        if a not in kwonlyargs_merged:
+            kwonlyargs_merged.append(a)
+
+    args_all = tuple(args_merged + kwonlyargs_merged)
+
+    if PY38:
+        replace_kwargs = {
+            "co_argcount": len(args_merged),
+            "co_kwonlyargcount": len(kwonlyargs_merged),
+            "co_posonlyargcount": dest.__code__.co_posonlyargcount,
+            "co_nlocals": len(args_all),
+            "co_flags": source.__code__.co_flags,
+            "co_varnames": args_all,
+            "co_filename": dest.__code__.co_filename,
+            "co_name": dest.__code__.co_name,
+            "co_firstlineno": dest.__code__.co_firstlineno,
+        }
+
+        if PY310:
+            replace_kwargs["co_linetable"] = dest.__code__.co_linetable
+        else:
+            replace_kwargs["co_lnotab"] = dest.__code__.co_lnotab
+
+        if PY311:
+            replace_kwargs["co_exceptiontable"] = dest.__code__.co_exceptiontable
+            replace_kwargs["co_qualname"] = dest.__code__.co_qualname
+
+        passer_code = _blank.__code__.replace(**replace_kwargs)
+    else:
+        passer_args = [
+            len(args_merged),
+            len(kwonlyargs_merged),
+            _blank.__code__.co_nlocals,
+            _blank.__code__.co_stacksize,
+            source.__code__.co_flags,
+            _blank.__code__.co_code,
+            (),
+            (),
+            args_all,
+            dest.__code__.co_filename,
+            dest.__code__.co_name,
+            dest.__code__.co_firstlineno,
+            dest.__code__.co_lnotab,
+        ]
+        passer_code = types.CodeType(*passer_args)
+
+    passer = types.FunctionType(passer_code, globals())
+    dest.__wrapped__ = passer
+
+    # annotations
+
+    # ensure we take destination’s return annotation
+    has_dest_ret = "return" in dest.__annotations__
+    if has_dest_ret:
+        dest_ret = dest.__annotations__["return"]
+
+    for v in ("__kwdefaults__", "__annotations__"):
+        out = getattr(source, v)
+        if out is None:
+            out = {}
+        if getattr(dest, v) is not None:
+            out = out.copy()
+            out.update(getattr(dest, v))
+            setattr(passer, v, out)
+
+    if has_dest_ret:
+        passer.__annotations__["return"] = dest_ret
+    dest.__annotations__ = passer.__annotations__
+
+    passer.__defaults__ = tuple(defaults_merged)
+    if not dest.__doc__:
+        dest.__doc__ = source.__doc__
+    return dest
+
+
+def merge_args(source):
+    """Merge the signatures of two functions."""
+    return functools.partial(_merge, source)

thds/core/meta.json

@@ -0,0 +1,8 @@
+{
+  "git_commit": "b374dd32673467abb1c76990d4aaade7f6562eba",
+  "git_branch": "main",
+  "git_is_clean": true,
+  "pyproject_version": "1.31.20250123022540",
+  "thds_user": "runner",
+  "misc": {}
+}