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

thds/core/lazy.py

@@ -0,0 +1,83 @@
+"""A thread-safe lazy callable."""
+
+import typing as ty
+from threading import Lock, local
+
+R = ty.TypeVar("R")
+_LOCK_LOCK = Lock()  # for thread local storage, you need to create the lock on each thread.
+
+
+def _get_or_create_lock(storage) -> Lock:
+    """Ensures a lock is available on this storage object. Holds a global lock to make
+    sure there is only ever one lock created for this storage object.
+
+    Storage can be any object that can have an attribute assigned with __setattr__.
+    """
+    if hasattr(storage, "lock"):
+        return storage.lock
+    with _LOCK_LOCK:
+        if hasattr(storage, "lock"):
+            return storage.lock
+        # creating a lock is itself very fast, whereas the source() callable may be slow.
+        storage.lock = Lock()
+    return storage.lock
+
+
+class Lazy(ty.Generic[R]):
+    """Ensures that the zero-argument callable (thunk) is called either 0 or 1 times for
+    the lifetime of this wrapper and its internal storage.
+
+    Most commonly, this wraps a singleton defined at module scope, but it could also be
+    used for shorter-lifetime singletons.
+
+    If thread-local storage is provided, then the wrapper will be called 0 or 1 times per
+    thread.
+    """
+
+    def __init__(self, source: ty.Callable[[], R], storage=None):
+        self._source = source
+        self._storage = storage if storage is not None else lambda: 0
+        self._storage.lock = Lock()
+        # we store the Lock on the storage, because in some cases the storage may be
+        # thread-local, and we need a separate lock per thread. However, we also create
+        # the first lock in the constructor so that in most cases, we never need to use
+        # the global _LOCK_LOCK, which will cause some very minor contention.
+
+    def __call__(self) -> R:
+        if hasattr(self._storage, "cached"):
+            return self._storage.cached
+        with _get_or_create_lock(self._storage):
+            if hasattr(self._storage, "cached"):
+                return self._storage.cached
+            self._storage.cached = self._source()
+        return self._storage.cached
+
+    def __repr__(self) -> str:
+        return f"Lazy({self._source})"
+
+    if not ty.TYPE_CHECKING:
+        # if I don't 'guard' it this way, mypy (unhelpfully) allows all attribute access (as Any)
+        def __getattr__(self, name: str) -> ty.NoReturn:
+            raise AttributeError(
+                f"{self} has no attribute '{name}' -"
+                f" did you mean to instantiate the object before access, i.e. `().{name}`?"
+            )
+
+
+class ThreadLocalLazy(Lazy[R]):
+    """A Lazy (see docs above), but with thread-local storage."""
+
+    def __init__(self, source: ty.Callable[[], R]):
+        # local() creates a brand new instance every time it is called,
+        # so this does not cause issues with storage being shared across multiple TTLazies
+        super().__init__(source, storage=local())
+
+
+def lazy(source: ty.Callable[[], R]) -> ty.Callable[[], R]:
+    """Wraps a thunk so that it is called at most once, and the result is cached."""
+    return Lazy(source)
+
+
+def threadlocal_lazy(source: ty.Callable[[], R]) -> ty.Callable[[], R]:
+    """Wraps a thunk so that it is called at most once per thread, and the result is cached."""
+    return ThreadLocalLazy(source)

thds/core/link.py

@@ -0,0 +1,153 @@
+"""Best-effort to link a destination to a source depending on file system support."""
+
+import os
+import platform
+import shutil
+import subprocess
+import typing as ty
+from pathlib import Path
+
+from . import log, tmp
+from . import types as ct
+
+_IS_MAC = platform.system() == "Darwin"
+logger = log.getLogger(__name__)
+
+
+LinkType = ty.Literal["same", "ref", "hard", "soft", ""]
+
+
+def _dest_parent(dest: ct.StrOrPath) -> Path:
+    """Returns the parent directory that exists.
+
+    If it does not exist, raises an exception.
+    """
+    dest_parent = Path(dest).parent
+    if not dest_parent.exists():
+        raise FileNotFoundError(f"Destination directory {dest_parent} does not exist")
+    if not dest_parent.is_dir():
+        raise NotADirectoryError(f"Destination {dest_parent} is not a directory")
+    return dest_parent
+
+
+def link(
+    src: ct.StrOrPath,
+    dest: ct.StrOrPath,
+    *attempt_types: LinkType,
+) -> LinkType:
+    """Attempt reflink, then hardlink, then softlink.
+
+    The destination directory must already exist.
+
+    Return a non-empty string of type LinkType if a link was successful.
+
+    Return empty string if no link could be created.
+    """
+    if not attempt_types:
+        attempt_types = ("ref", "hard", "soft")
+    src = Path(src).resolve()
+    if src == Path(dest).resolve():
+        return "same"
+    assert os.path.exists(src), f"Source {src} does not exist"
+
+    dest_parent = _dest_parent(dest)
+    with tmp.temppath_same_fs(dest_parent) as tmp_link_dest:
+        # links will _fail_ if the destination already exists.
+        # Therefore, instead of linking directly to the destination,
+        # we always create the link at a temporary file on the same filesystem
+        # as the true destination. Then, we take advantage of atomic moves
+        # within the same filesystem, because moves of links are themselves atomic!
+        # https://unix.stackexchange.com/a/81900
+        assert not tmp_link_dest.exists(), tmp_link_dest
+        if _IS_MAC and "ref" in attempt_types:
+            try:
+                subprocess.check_output(["cp", "-c", str(src), str(tmp_link_dest)])
+                os.rename(tmp_link_dest, dest)
+                logger.debug(f"Created a copy-on-write reflink from {src} to {dest}")
+                return "ref"
+            except subprocess.CalledProcessError:
+                pass
+        if "hard" in attempt_types:
+            try:
+                os.link(src, tmp_link_dest)
+                os.rename(tmp_link_dest, dest)
+                logger.debug(f"Created a hardlink from {src} to {dest}")
+                return "hard"
+            except OSError as oserr:
+                logger.warning(f"Unable to hard-link {src} to {dest} ({oserr})")
+        if "soft" in attempt_types:
+            try:
+                os.symlink(src, tmp_link_dest)
+                os.rename(tmp_link_dest, dest)
+                logger.debug(f"Created a softlink from {src} to {dest}")
+                return "soft"
+            except OSError as oserr:
+                logger.warning(f"Unable to soft-link {src} to {dest}" f" ({oserr})")
+
+    return ""
+
+
+def reify_if_link(path: Path):
+    """Turn a softlink to a target file into a copy of the target file at the link location.
+
+    Useful for cases where a symlink crossing filesystems may not work
+    as expected, e.g. a Docker build.
+
+    No-op for anything that is not a symlink to a file.
+    """
+    if not path.is_symlink() or not path.is_file():
+        return
+    logger.info(f'Reifying softlink "{path}"')
+    dest = path.absolute()
+    src = path.resolve()
+    dest.unlink()
+    shutil.copy(src, dest)
+
+
+def link_or_copy(src: ct.StrOrPath, dest: ct.StrOrPath, *link_types: LinkType) -> LinkType:
+    """If you absolutely have to get your file to its destination, you should use this
+    over link(), which could theoretically fail under certain conditions.
+    """
+    if link_types:
+        link_success_type = link(src, dest, *link_types)
+        if link_success_type:
+            return link_success_type
+        logger.info(f"Unable to link {src} to {dest}; falling back to copy.")
+
+    logger.debug("Copying %s to %s", src, dest)
+    with tmp.temppath_same_fs(dest) as tmpfile:
+        # atomic to the final destination since we're on the same filesystem.
+        shutil.copyfile(src, tmpfile)
+        shutil.move(str(tmpfile), dest)
+    return ""
+
+
+def cheap_copy(
+    src: ct.StrOrPath,
+    dest: ct.StrOrPath,
+    *,
+    permissions: ty.Optional[int] = None,
+) -> Path:
+    """Make a copy of the file, but first attempt Mac COW semantics if available.
+
+    The copy will be done via a temporary file on the same filesystem as the destination,
+    so it will 'appear' atomic at the destination.
+
+    If provided, the given permissions will be applied to the destination prior to the
+    atomic move.
+    """
+    dest_parent = _dest_parent(dest)
+    with tmp.temppath_same_fs(dest_parent) as tmp_link_dest:
+        cow_success = False
+        if _IS_MAC:
+            try:
+                subprocess.check_output(["cp", "-c", os.fspath(src), str(tmp_link_dest)])
+                cow_success = True
+            except subprocess.CalledProcessError:
+                pass
+        if not cow_success:
+            shutil.copyfile(src, tmp_link_dest)
+        if permissions is not None:
+            os.chmod(tmp_link_dest, permissions)
+        os.rename(tmp_link_dest, dest)
+    return Path(dest)

thds/core/log/__init__.py

@@ -0,0 +1,29 @@
+"""New and improved logger for Trilliant.
+Now you can add keyword arguments to your log statements and they will
+get formatted nicely in the logging message. If we ever move to
+structured/JSON logging, we can write a useful Formatter for that
+scenario as well.
+Additionally, you can add additional context (via keyword arguments)
+to logs at any time by inserting a logger_context, and this context
+will accompany all future logging statements further down the stack,
+but not once it has been exited.
+Observe:
+```
+logger = getLogger("FooF")
+logger.warning("testing")
+# 2022-02-18 10:01:16,825 WARNING  FooF () testing 1
+logger.info("testing 2", two=3, eight="nine")
+# 2022-02-18 10:01:16,826 info     FooF (two=3,eight=nine) testing 2
+with logger_context(App='bat', override='me'):
+    logger.info("testing 3", yes='no')
+# 2022-02-18 10:01:16,827 info     FooF (App=bat,override=me,yes=no) testing 3
+    logger.info("testing 4", override='you')
+# 2022-02-18 10:01:16,828 info     FooF (App=bat,override=you) testing 4
+logger.info("testing 5")
+# 2022-02-18 10:01:16,829 info     FooF () testing 5
+```
+"""
+
+from .basic_config import DuplicateFilter, set_logger_to_console_level  # noqa: F401
+from .kw_formatter import ThdsCompactFormatter  # noqa: F401
+from .kw_logger import KwLogger, getLogger, logger_context, make_th_formatters_safe  # noqa: F401

thds/core/log/basic_config.py

@@ -0,0 +1,171 @@
+"""Contains the basic configuration for our logger. By importing thds.core.log, you import
+and 'use' this configuration.
+"""
+
+import logging
+import logging.config
+import os
+import sys
+import typing as ty
+from datetime import datetime
+from pathlib import Path
+from typing import Iterator, Tuple
+
+from .. import config, home
+from .json_formatter import ThdsJsonFormatter
+from .kw_formatter import ThdsCompactFormatter
+from .kw_logger import getLogger, make_th_formatters_safe
+from .logfmt import mk_default_logfmter
+
+_LOG_FILEPATH = os.getenv(
+    "THDS_CORE_LOG_FILEPATH",
+    str(
+        # we're logging to a file by default now. Set this to empty string to turn off.
+        # It's not a config item because it can't usefully be set after startup.
+        home.HOMEDIR()
+        / ".thds-logs"
+        / "-".join(
+            [
+                datetime.now().isoformat(),
+                f"ppid_{os.getppid()}",
+                f"pid_{os.getpid()}",
+                f"{'_'.join(sys.argv)[:150]}.log",
+            ]
+        ).replace("/", "_")
+    ),
+)
+
+
+_LOGLEVEL = config.item("thds.core.log.level", logging.INFO, parse=logging.getLevelName)
+_LOGLEVELS_FILEPATH = config.item("thds.core.log.levels_file", "", parse=lambda s: s.strip())
+# see _parse_thds_loglevels_file for format of this file.
+
+FORMAT = config.item("thds.core.log.format", "")  # valid options are 'logfmt', 'json', and ''.
+
+
+def _pick_formatter() -> ty.Callable[[], logging.Formatter]:
+    if FORMAT() == "logfmt":
+        return mk_default_logfmter
+    if FORMAT() == "json":
+        return ThdsJsonFormatter
+    return ThdsCompactFormatter
+
+
+# this is the base of what gets passed to logging.dictConfig.
+_BASE_LOG_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {"default": {"()": _pick_formatter()}},
+    "handlers": {"console": {"class": "logging.StreamHandler", "formatter": "default"}},
+    "root": {"handlers": ["console"], "level": _LOGLEVEL()},
+}
+
+
+def set_logger_to_console_level(config: dict, logger_name: str, level: int) -> dict:
+    if logger_name == "*":
+        if level != _LOGLEVEL():
+            getLogger(__name__).warning(f"Setting root logger to {logging.getLevelName(level)}")
+        return dict(config, root=dict(config["root"], level=level))
+    loggers = config.get("loggers") or dict()
+    loggers = {**loggers, logger_name: {"level": level, "handlers": ["console"], "propagate": False}}
+    # propagate=False means, don't pass this up the chain to loggers
+    # matching a subset of our name.  The level is set on the logger,
+    # not the handler, but if a logger is set to propagate,then it
+    # will pass its message up the chain until it hits propagate=False
+    # or the root. And any loggers with the appropriate logging level
+    # will emit to any handlers they have configured. So, generally,
+    # you want to put handlers at the same level where
+    # propagate=False, which is what we do here.
+    return dict(config, loggers=loggers)
+
+
+def _parse_thds_loglevels_file(filepath: str) -> Iterator[Tuple[str, int]]:
+    """Example loglevels file:
+
+    ```
+    [debug]
+    thds.adls.download
+    thds.mops.pure.pickle_runner
+    thds.nppes.intake.parquet_from_csv
+
+    [warning]
+    *
+    # the * sets the root logger to warning-and-above. INFO is the default.
+    ```
+
+    The last value encountered for any given logger (or the root) will
+    override any previous values.
+    """
+    current_level = _LOGLEVEL()
+    if not os.path.exists(filepath):
+        return
+    with open(filepath) as f:
+        for line in f.readlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if line.startswith("[") and line.endswith("]"):
+                current_level = getattr(
+                    logging, line[1:-1].upper()
+                )  # AttributeError means invalid level
+                continue
+            logger_name = line
+            yield logger_name, current_level
+
+
+class DuplicateFilter:
+    """Filters away duplicate log messages.
+
+    Taken from @erb's answer on SO: https://stackoverflow.com/questions/31953272/logging-print-message-only-once
+    """
+
+    def __init__(self, logger: ty.Union[logging.Logger, logging.LoggerAdapter]):
+        self.msgs: ty.Set[str] = set()
+        self.logger = logger.logger if isinstance(logger, logging.LoggerAdapter) else logger
+
+    def filter(self, record: logging.LogRecord):
+        msg = str(record.msg)
+        is_duplicate = msg in self.msgs
+        if not is_duplicate:
+            self.msgs.add(msg)
+        return not is_duplicate
+
+    def __enter__(self):
+        self.logger.addFilter(self)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.logger.removeFilter(self)
+
+
+if not logging.getLogger().hasHandlers():
+    live_config = _BASE_LOG_CONFIG
+    for logger_name, level in _parse_thds_loglevels_file(_LOGLEVELS_FILEPATH()):
+        live_config = set_logger_to_console_level(live_config, logger_name, level)
+
+    if _LOG_FILEPATH:
+        log_path = Path(_LOG_FILEPATH)
+        try:
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            # ^ I hate doing IO in module scope, but we've waited until the last possible moment...
+            live_config["handlers"]["file"] = {  # type: ignore
+                "class": "logging.FileHandler",
+                "formatter": "default",
+                "filename": _LOG_FILEPATH,
+                "delay": True,  # no need to have empty logfiles sitting around
+            }
+            live_config["root"]["handlers"].append("file")  # type: ignore
+        except Exception as err:
+            print(f"Unable to create log directory at '{log_path.parent}' - ERROR: {err}")
+
+    logging.config.dictConfig(live_config)
+    make_th_formatters_safe(logging.getLogger())
+
+    class StartsWithFilter(logging.Filter):
+        def __init__(self, startswith: str):
+            self.startswith = startswith
+
+        def filter(self, record):
+            return not record.name.startswith(self.startswith)
+
+    for noisy_logger in ("py4j.java_gateway", "py4j.clientserver"):  # 11.3, 9.1
+        logging.getLogger(noisy_logger).addFilter(StartsWithFilter(noisy_logger))

thds/core/log/json_formatter.py

@@ -0,0 +1,43 @@
+"""A JSON formatter that understands what to do with our keyword logger things."""
+
+import json
+import logging
+
+from .kw_logger import th_keyvals_from_record
+
+
+class ThdsJsonFormatter(logging.Formatter):
+    def _format_exception_and_trace(self, record: logging.LogRecord):
+        # without the following boilerplate, we would not see exceptions or stack traces
+        # get formatted as part of the log output at all.
+        formatted = ""
+        if record.exc_info:
+            if not record.exc_text:
+                record.exc_text = self.formatException(record.exc_info)
+        if record.exc_text:
+            formatted += "\n" + record.exc_text
+        if record.stack_info:
+            formatted += "\n" + self.formatStack(record.stack_info)
+        return formatted
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format the record as a JSON string."""
+        # We're going to use a dictionary to hold the record data, and then convert it to JSON.
+        # This is because we want to be able to add arbitrary key-value pairs to the log record
+        # and have them show up in the JSON output.
+        record_dict = {
+            "timestamp": self.formatTime(record),
+            "level": record.levelname,
+            "module": record.module,
+            "msg": record.getMessage(),
+        }
+        # Add the extra data, if it exists.
+        if record.__dict__.get("extra"):
+            record_dict.update(record.__dict__["extra"])
+        record_dict.update(th_keyvals_from_record(record) or {})
+
+        # Convert the dictionary to a JSON string.
+        formatted = json.dumps(record_dict)
+        if exc_text := self._format_exception_and_trace(record):
+            formatted += exc_text
+        return formatted

thds/core/log/kw_formatter.py

@@ -0,0 +1,84 @@
+"""This is the 'standard' keyword-formatting logger formatter for our logs.
+
+It is enabled by default via basic_config.py, but is not required.
+"""
+
+import logging
+import typing as ty
+
+from .. import ansi_esc, config
+from .kw_logger import th_keyvals_from_record
+
+MAX_MODULE_NAME_LEN = config.item("max_module_name_len", 40, parse=int)
+_MODULE_NAME_FMT_STR = "{compressed_name:" + str(MAX_MODULE_NAME_LEN()) + "}"
+
+_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.bg.ERROR_RED}{ansi_esc.style.BRIGHT}"
+        "{}"
+        f"{ansi_esc.style.NORMAL}{ansi_esc.bg.RESET}"
+    ),
+    "critical": (
+        f"{ansi_esc.bg.MAGENTA}{ansi_esc.style.BRIGHT}{ansi_esc.style.BLINK}"  # 😂
+        "{}"
+        f"{ansi_esc.bg.RESET}{ansi_esc.style.NORMAL}{ansi_esc.style.NO_BLINK}"
+    ),
+}
+
+
+def log_level_color(levelno: int, base_levelname: str) -> str:
+    if levelno < logging.INFO:
+        return _COLOR_LEVEL_MAP["low"].format(base_levelname.lower())
+    elif levelno < logging.WARNING:
+        return _COLOR_LEVEL_MAP["info"].format(base_levelname.lower())
+    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 ThdsCompactFormatter(logging.Formatter):
+    """This new formatter is more compact than what we had before, and hopefully makes logs a bit more readable overall."""
+
+    @staticmethod
+    def format_module_name(name: str) -> str:
+        max_module_name_len = MAX_MODULE_NAME_LEN()
+        compressed_name = (
+            name
+            if len(name) <= max_module_name_len
+            else name[: max_module_name_len // 2 - 2] + "..." + name[-max_module_name_len // 2 + 1 :]
+        )
+        assert len(compressed_name) <= max_module_name_len
+        return _MODULE_NAME_FMT_STR.format(compressed_name=compressed_name)
+
+    def _format_exception_and_trace(self, record: logging.LogRecord):
+        # without the following boilerplate, we would not see exceptions or stack traces
+        # get formatted as part of the log output at all.
+        formatted = ""
+        if record.exc_info:
+            if not record.exc_text:
+                record.exc_text = self.formatException(record.exc_info)
+        if record.exc_text:
+            formatted += "\n" + record.exc_text
+        if record.stack_info:
+            formatted += "\n" + self.formatStack(record.stack_info)
+        return formatted
+
+    def format(self, record: logging.LogRecord):
+        record.message = record.getMessage()
+
+        base_levelname = f"{record.levelname:7}"  # the length of the string 'WARNING'
+        levelname = log_level_color(record.levelno, base_levelname)
+
+        th_ctx: ty.Any = th_keyvals_from_record(record) or tuple()
+        short_name = self.format_module_name(record.name)
+        formatted = f"{self.formatTime(record)} {levelname}  {short_name} {th_ctx} {record.message}"
+        if exc_text := self._format_exception_and_trace(record):
+            formatted += exc_text
+        return formatted

thds/core/log/kw_logger.py

@@ -0,0 +1,93 @@
+"""A logger which allows passing of arbitrary keyword arguments to the end of a logger call,
+such that that context gets embedded directly into the output in one way or another.
+"""
+
+import contextlib
+import logging
+import logging.config
+from copy import copy
+from typing import Any, Dict, MutableMapping, Optional
+
+from ..stack_context import StackContext
+
+_LOGGING_KWARGS = ("exc_info", "stack_info", "stacklevel", "extra")
+# These are the officially accepted keyword-arguments for a call to
+# log something with the logger. Anything passed with these names
+# should be passed through directly - anything else can be passed through
+# to the keyword formatter.
+
+TH_REC_CTXT = "th_context"
+# this names a nested dict on some LogRecords that contains things we
+# want to log. It is usable as a field specifier in log format strings
+
+
+class _THContext(Dict[str, Any]):
+    def __str__(self):
+        return ",".join(map("(%s=%s)".__mod__, self.items())) if self else "()"
+
+
+_LOG_CONTEXT: StackContext[_THContext] = StackContext("TH_LOG_CONTEXT", _THContext())
+
+
+@contextlib.contextmanager
+def logger_context(**kwargs):
+    """Put some key-value pairs into the keyword-based logger context."""
+    with _LOG_CONTEXT.set(_THContext(_LOG_CONTEXT(), **kwargs)):
+        yield
+
+
+def _embed_th_context_in_extra_kw(kwargs: MutableMapping[str, Any]) -> MutableMapping[str, Any]:
+    """Extracts the key-value pairs embedded via `logger_context, overlays those with
+    keyword arguments to the logger, and embeds them all in the logger's "extra" dictionary.
+    """
+    th_context = _LOG_CONTEXT()
+    th_kwargs = [k for k in kwargs if k not in _LOGGING_KWARGS]
+    if th_kwargs:
+        th_context = copy(th_context)
+        th_context.update((k, kwargs.pop(k)) for k in th_kwargs)
+    extra = kwargs["extra"] = kwargs.get("extra", dict())
+    extra[TH_REC_CTXT] = th_context
+    return kwargs
+
+
+class KwLogger(logging.LoggerAdapter):
+    """Allows logging of extra keyword arguments straight through without
+    needing an "extras" dictionary.
+    """
+
+    def process(self, msg, kwargs):
+        return msg, _embed_th_context_in_extra_kw(kwargs)
+
+
+def th_keyvals_from_record(record: logging.LogRecord) -> Optional[Dict[str, Any]]:
+    """Extracts the key-value pairs embedded via `logger_context` or keyword arguments from a LogRecord."""
+    return getattr(record, TH_REC_CTXT, None)
+
+
+def getLogger(name: Optional[str] = None) -> logging.LoggerAdapter:
+    """Using this Logger Adapter will allow you to pass key/value context at the end of
+    your logging statements, e.g. `logger.info("my message", key1=value1, key2=value2)`.
+    Provided that you haven't configured your own logging format, this module will do so for you,
+    ensuring that these contextual key-value pairs render in your log messages. To ensure their presence
+    when configuring logging yourself, just put a "%(th_context)s" format specifier somewhere in your
+    log message format.
+    """
+    return KwLogger(logging.getLogger(name), dict())
+
+
+def make_th_formatters_safe(logger: logging.Logger):
+    """Non-adapted loggers may still run into our root format string,
+    which expects _TH_REC_CTXT to be present on every LogRecord.
+    This will patch one in to any logs making it to our configured formatter.
+    """
+    for handler in logger.handlers:
+        formatter = handler.formatter
+        if formatter and hasattr(formatter, "_style") and TH_REC_CTXT in formatter._style._fmt:
+            fmt_msg = formatter.formatMessage
+
+            def wrapper_formatMessage(record: logging.LogRecord):
+                if None is getattr(record, TH_REC_CTXT, None):
+                    setattr(record, TH_REC_CTXT, _LOG_CONTEXT())
+                return fmt_msg(record)  # noqa: B023
+
+            setattr(formatter, "formatMessage", wrapper_formatMessage)  # noqa: B010