python-devlog 1.1__py3-none-any.whl → 2.0__py3-none-any.whl

devlog/__init__.py

@@ -1,9 +1,8 @@
 from .custom_excepthook import system_excepthook_overwrite
-from .decorator import LogOnStart, LogOnError, LogOnEnd
-from .stack_trace import set_stack_removal_frames, set_stack_start_frames
+from .decorators import LogOnStart, LogOnError, LogOnEnd
+from .sanitize import Sensitive
 
-__all__ = ["log_on_start", "log_on_end", "log_on_error", "system_excepthook_overwrite", "set_stack_removal_frames",
-           "set_stack_start_frames"]
+__all__ = ["log_on_start", "log_on_end", "log_on_error", "system_excepthook_overwrite", "Sensitive"]
 
 
 def log_on_start(*args, **kwargs):

devlog/base.py

@@ -0,0 +1,184 @@
+import asyncio
+import inspect
+import logging
+import sys
+import traceback
+from functools import wraps
+from logging import Logger, Handler
+from types import FunctionType
+from typing import Any, Callable, Dict, Optional, Set, Tuple, Type, Union
+from warnings import warn
+
+from .sanitize import Sensitive, unwrap_sensitive, format_value
+
+
+class WrapCallback:
+    r"""A callback that wraps the function and executes it.
+
+    This class is designed to be used as a mix-in for logging callables,
+    such as functions or methods. These are not created manually, instead
+    they are created from other log decorators in this package.
+    """
+
+    # default execute wrapped function
+    def _devlog_executor(self, fn: FunctionType, *args: Any, **kwargs: Any) -> Any:
+        __tracebackhide__ = True
+        return fn(*args, **kwargs)
+
+    async def _async_devlog_executor(self, fn: FunctionType, *args: Any, **kwargs: Any) -> Any:
+        __tracebackhide__ = True
+        return await fn(*args, **kwargs)
+
+    def __call__(self, fn: FunctionType) -> Callable[..., Any]:
+        if asyncio.iscoroutinefunction(fn):
+            @wraps(fn)
+            async def devlog_wrapper(*args: Any, **kwargs: Any) -> Any:
+                __tracebackhide__ = True
+                return await self._async_devlog_executor(fn, *args, **kwargs)
+        else:
+            @wraps(fn)
+            def devlog_wrapper(*args: Any, **kwargs: Any) -> Any:
+                __tracebackhide__ = True
+                return self._devlog_executor(fn, *args, **kwargs)
+
+        return devlog_wrapper
+
+
+class LoggingDecorator(WrapCallback):
+    r"""A class that implements the protocol for a logging callable.
+
+    This class are responsible for create logging message for the function
+    and log it.
+
+    Attributes:
+        log_level: The log level to use for logging.
+        message: The message format for the log.
+        logger: The logger to use for logging.
+            If not set, the logger will be created using the module name of the function.
+        handler: The handler to use for logging.
+        callable_format_variable: The name of the variable to use for the callable.
+        args_kwargs: If True, the message will accept {args} {kwargs} format.
+        trace_stack: Whether to include the stack trace in the log.
+        capture_locals: Capture the locals of the function.
+        include_decorator: Whether to include the decorator in the trace log.
+        sanitize_params: Set of parameter names to auto-redact in logs.
+    """
+
+    # Global default for sanitize_params
+    default_sanitize_params: Optional[Set[str]] = None
+
+    # Files to exclude from stack traces (populated by submodules)
+    _internal_files: Set[str] = set()
+
+    def __init__(self, log_level: int, message: str, *, logger: Optional[Logger] = None,
+                 handler: Optional[Handler] = None, args_kwargs: bool = True,
+                 callable_format_variable: str = "callable",
+                 trace_stack: bool = False, capture_locals: bool = False,
+                 include_decorator: bool = False,
+                 sanitize_params: Optional[Set[str]] = None):
+        self.log_level = log_level
+        self.message = message
+
+        if logger is not None and handler is not None:
+            warn("logger and handler are both set, the handler will be ignored")
+            handler = None
+
+        self._logger = logger
+        self._handler = handler
+
+        self.callable_format_variable = callable_format_variable
+        self.include_decorator = include_decorator
+        self.trace_stack = trace_stack or capture_locals
+        self.capture_locals = capture_locals
+        self.args_kwargs = args_kwargs
+        self.sanitize_params = sanitize_params if sanitize_params is not None else self.default_sanitize_params
+
+    @staticmethod
+    def log(logger: Logger, log_level: int, msg: str) -> None:
+        logger.log(log_level, msg)
+
+    def get_logger(self, fn: FunctionType) -> Logger:
+        """
+        Returns the logger to use for logging.
+        if the logger is not set, the logger will be created using the module name of the function.
+        and the handler will be added to the logger if any.
+        """
+        if self._logger is None:
+            self._logger = logging.getLogger(fn.__module__)
+
+            if self._handler is not None:
+                self._logger.addHandler(self._handler)
+
+        return self._logger
+
+    @classmethod
+    def _is_internal_file(cls, filename: str) -> bool:
+        return filename in cls._internal_files
+
+    @classmethod
+    def get_stack_summary(cls, include_decorator: bool, *args: Any, **kwargs: Any):
+        stack = traceback.StackSummary.extract(traceback.walk_stack(None), *args, **kwargs)
+        stack.reverse()
+
+        for frame in stack:
+            if include_decorator or not cls._is_internal_file(frame.filename):
+                yield frame
+
+    @staticmethod
+    def bind_param(fn: FunctionType, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Returns a dictionary with all the `parameter`: `value` in the function.
+        """
+        callable_signature = inspect.signature(fn)
+        bound_arguments = callable_signature.bind(*args, **kwargs)
+        bounded_param = {param_name: bound_arguments.arguments.get(param_name, param_object.default) for
+                         param_name, param_object in bound_arguments.signature.parameters.items()}
+
+        return bounded_param
+
+    def _sanitize_bound_params(self, bound_params: Dict[str, Any]) -> Dict[str, str]:
+        """Format bound params with sanitization applied."""
+        result = {}
+        for name, value in bound_params.items():
+            result[name] = format_value(value, name, self.sanitize_params)
+        return result
+
+    def build_msg(self, fn: FunctionType, fn_args: Any, fn_kwargs: Any, **extra: Any) -> str:
+        """
+        Builds the message log using the message format and the function arguments.
+        """
+        format_kwargs = extra
+
+        if self.args_kwargs:
+            # Sanitize args and kwargs for display
+            sanitized_args = tuple(
+                format_value(a, sanitize_params=self.sanitize_params) for a in fn_args
+            ) if self.sanitize_params or any(isinstance(a, Sensitive) for a in fn_args) else fn_args
+            sanitized_kwargs = {
+                k: format_value(v, k, self.sanitize_params) for k, v in fn_kwargs.items()
+            } if self.sanitize_params or any(isinstance(v, Sensitive) for v in fn_kwargs.values()) else fn_kwargs
+            format_kwargs["args"] = sanitized_args
+            format_kwargs["kwargs"] = sanitized_kwargs
+        else:
+            bound = self.bind_param(fn, *fn_args, **fn_kwargs)
+            if self.sanitize_params or any(isinstance(v, Sensitive) for v in bound.values()):
+                format_kwargs.update(self._sanitize_bound_params(bound))
+            else:
+                format_kwargs.update(bound)
+        return self.message.format(**format_kwargs)
+
+    @staticmethod
+    def _unwrap_args(args: tuple, kwargs: dict) -> Tuple[tuple, dict]:
+        """Unwrap Sensitive values before passing to the actual function."""
+        unwrapped_args = tuple(unwrap_sensitive(a) for a in args)
+        unwrapped_kwargs = {k: unwrap_sensitive(v) for k, v in kwargs.items()}
+        return unwrapped_args, unwrapped_kwargs
+
+    def _has_sensitive(self, args: tuple, kwargs: dict) -> bool:
+        """Check if any args/kwargs contain Sensitive values."""
+        return any(isinstance(a, Sensitive) for a in args) or \
+               any(isinstance(v, Sensitive) for v in kwargs.values())
+
+
+# Register this file as internal
+LoggingDecorator._internal_files.add(__file__)

devlog/custom_excepthook.py

@@ -1,33 +1,47 @@
+import sys
 import traceback
+from typing import Optional, Type
+from types import TracebackType
 
-output_file = "crash.log"
-
-
-def my_except_hook(exception_type, exception_value, traceback_message):
-    # traceback.print_tb(traceback_message)
-    with open(output_file, encoding="utf-8") as f:
-        # save to file
-        traceback.print_exception(exception_type, exception_value, traceback_message, file=f)
-        print("Stack (most recent stack last):", file=f)
-        # output to stdout
-        traceback.print_exception(exception_type, exception_value, traceback_message)
-        for frame in traceback.TracebackException.from_exception(exception_value, capture_locals=True).stack[1:]:
-            # save to a file
-            message = "\t{filename}:{lineno} on {line}\n\t\t{locals}".format(
-                filename=frame.filename,
-                lineno=frame.lineno,
-                line=frame.line,
-                locals=frame.locals
-            )
-            print(message, file=f)
-            # output to stdout
-            print(message)
-
-
-def system_excepthook_overwrite(out_file=None):
-    import sys
-    global output_file
+
+_output_file: str = "crash.log"
+
+
+def my_except_hook(exception_type: Type[BaseException],
+                   exception_value: BaseException,
+                   traceback_message: Optional[TracebackType]) -> None:
+    """Custom exception hook that writes crash info to a file and stdout."""
+    tb_exception = traceback.TracebackException(
+        exception_type, exception_value, traceback_message,
+        capture_locals=True
+    )
+
+    formatted = "".join(tb_exception.format())
+
+    # Print to stdout
+    print(formatted, end="")
+
+    # Write to file
+    try:
+        with open(_output_file, encoding="utf-8", mode="w") as f:
+            f.write(formatted)
+            f.write("\nStack (most recent stack last):\n")
+            for frame in tb_exception.stack:
+                message = "\t{filename}:{lineno} on {line}\n\t\t{locals}".format(
+                    filename=frame.filename,
+                    lineno=frame.lineno,
+                    line=frame.line,
+                    locals=frame.locals
+                )
+                f.write(message + "\n")
+    except OSError as e:
+        print(f"devlog: Failed to write crash log to {_output_file}: {e}", file=sys.stderr)
+
+
+def system_excepthook_overwrite(out_file: Optional[str] = None) -> None:
+    """Override sys.excepthook to write crash logs with local variable capture."""
+    global _output_file
 
     if out_file is not None:
-        output_file = out_file
+        _output_file = out_file
     sys.excepthook = my_except_hook

devlog/decorators.py

@@ -0,0 +1,212 @@
+import asyncio
+import logging
+import sys
+import traceback
+from types import FunctionType
+from typing import Any, Optional, Tuple, Type, Union
+
+from .base import WrapCallback, LoggingDecorator
+
+
+class LogOnStart(LoggingDecorator):
+    r"""A logging decorator that logs the start of the function.
+
+    This decorator will log the start of the function using the logger and the handler
+    provided in the constructor.
+
+    Attributes:
+        log_level: The log level to use for logging.
+        message: The message format for the log.
+        logger: The logger to use for logging.
+            If not set, the logger will be created using the module name of the function.
+        handler: The handler to use for logging.
+        callable_format_variable: The name of the variable to use for the callable.
+        args_kwargs: If True, the message will accept {args} {kwargs} format.
+        trace_stack: Whether to include the stack trace in the log.
+        trace_stack_message:The message format for the stack trace log.
+    """
+
+    def __init__(self, log_level: int = logging.INFO,
+                 message: Optional[str] = None,
+                 **kwargs: Any):
+        super().__init__(log_level, message, **kwargs)
+        if message is None:
+            self.message = "Start func {{{cal_var}.__name__}} " \
+                           "with args {{args}}, kwargs {{kwargs}}".format(cal_var=self.callable_format_variable)
+
+    def _devlog_executor(self, fn: FunctionType, *args: Any, **kwargs: Any) -> Any:
+        __tracebackhide__ = True
+        self._do_logging(fn, *args, **kwargs)
+        if self._has_sensitive(args, kwargs):
+            args, kwargs = self._unwrap_args(args, kwargs)
+        return super()._devlog_executor(fn, *args, **kwargs)
+
+    async def _async_devlog_executor(self, fn: FunctionType, *args: Any, **kwargs: Any) -> Any:
+        __tracebackhide__ = True
+        self._do_logging(fn, *args, **kwargs)
+        if self._has_sensitive(args, kwargs):
+            args, kwargs = self._unwrap_args(args, kwargs)
+        return await super()._async_devlog_executor(fn, *args, **kwargs)
+
+    def _do_logging(self, fn: FunctionType, *args: Any, **kwargs: Any) -> None:
+        logger = self.get_logger(fn)
+        extra = {self.callable_format_variable: fn}
+        msg = self.build_msg(fn, fn_args=args, fn_kwargs=kwargs, **extra)
+
+        self.log(logger, self.log_level, msg)
+        if self.trace_stack:
+            stack = traceback.StackSummary(
+                LoggingDecorator.get_stack_summary(self.include_decorator, capture_locals=self.capture_locals)
+            )
+            self.log(logger, logging.DEBUG, "".join(stack.format()).strip())
+
+
+class LogOnEnd(LoggingDecorator):
+    r"""A logging decorator that logs the end of the function.
+
+    This decorator will log the end of the function using the logger and the handler
+    provided in the constructor.
+
+    Attributes:
+        log_level: The log level to use for logging.
+        message: The message format for the log.
+        logger: The logger to use for logging.
+            If not set, the logger will be created using the module name of the function.
+        handler: The handler to use for logging.
+        callable_format_variable: The name of the variable to use for the callable.
+        args_kwargs: If True, the message will accept {args} {kwargs} format.
+        trace_stack: Whether to include the stack trace in the log.
+        trace_stack_message:The message format for the stack trace log.
+        result_format_variable: The variable to use for the result.
+    """
+
+    def __init__(self, log_level: int = logging.INFO,
+                 message: Optional[str] = None, result_format_variable: str = "result",
+                 **kwargs: Any):
+        super().__init__(log_level, message, **kwargs)
+        if message is None:
+            self.message = "Successfully run func {{{cal_var}.__name__}} " \
+                           "with args {{args}}, kwargs {{kwargs}}".format(cal_var=self.callable_format_variable)
+        self.result_format_variable = result_format_variable
+
+    def _devlog_executor(self, fn: FunctionType, *args: Any, **kwargs: Any) -> Any:
+        __tracebackhide__ = True
+        original_args, original_kwargs = args, kwargs
+        if self._has_sensitive(args, kwargs):
+            args, kwargs = self._unwrap_args(args, kwargs)
+        result = super()._devlog_executor(fn, *args, **kwargs)
+        self._do_logging(fn, result, *original_args, **original_kwargs)
+        return result
+
+    async def _async_devlog_executor(self, fn: FunctionType, *args: Any, **kwargs: Any) -> Any:
+        __tracebackhide__ = True
+        original_args, original_kwargs = args, kwargs
+        if self._has_sensitive(args, kwargs):
+            args, kwargs = self._unwrap_args(args, kwargs)
+        result = await super()._async_devlog_executor(fn, *args, **kwargs)
+        self._do_logging(fn, result, *original_args, **original_kwargs)
+        return result
+
+    def _do_logging(self, fn: FunctionType, result: Any, *args: Any, **kwargs: Any) -> None:
+        logger = self.get_logger(fn)
+
+        extra = {self.result_format_variable: result, self.callable_format_variable: fn}
+        msg = self.build_msg(fn, fn_args=args, fn_kwargs=kwargs, **extra)
+
+        self.log(logger, self.log_level, msg)
+        if self.trace_stack:
+            stack = traceback.StackSummary(
+                LoggingDecorator.get_stack_summary(self.include_decorator, capture_locals=self.capture_locals)
+            )
+            self.log(logger, logging.DEBUG, "".join(stack.format()).strip())
+
+
+class LogOnError(LoggingDecorator):
+    r"""A logging decorator that logs the error of the function.
+
+    This decorator will log the error of the function using the logger and the handler
+    provided in the constructor.
+
+    Attributes:
+        log_level: The log level to use for logging.
+        message: The message format for the log.
+        logger: The logger to use for logging.
+            If not set, the logger will be created using the module name of the function.
+        handler: The handler to use for logging.
+        args_kwargs: If True, the message will accept {args} {kwargs} format.
+        trace_stack: Whether to include the stack trace in the log.
+        trace_stack_message:The message format for the stack trace log.
+        on_exception: The exception that will catch. Empty mean everything.
+        reraise: Whether to reraise the exception or supress it.
+        exception_format_variable: The variable to use for the error.
+    """
+
+    def __init__(self, log_level: int = logging.ERROR,
+                 message: Optional[str] = None,
+                 on_exceptions: Optional[Union[Type[BaseException], Tuple[Type[BaseException], ...]]] = None,
+                 reraise: bool = True, exception_format_variable: str = "error", **kwargs: Any):
+        super().__init__(log_level, message, **kwargs)
+        if message is None:
+            self.message = "Error in func {{{cal_var}.__name__}} " \
+                           "with args {{args}}, kwargs {{kwargs}}\n{{{except_var}}}.".format(
+                cal_var=self.callable_format_variable,
+                except_var=exception_format_variable
+            )
+        self.on_exceptions: Union[Type[BaseException], Tuple[Type[BaseException], ...]] = on_exceptions if \
+            on_exceptions is not None else BaseException
+        self.reraise = reraise
+        self.exception_format_variable = exception_format_variable
+        self.capture_locals = self.trace_stack or self.capture_locals
+
+    def _devlog_executor(self, fn: FunctionType, *args: Any, **kwargs: Any) -> Any:
+        __tracebackhide__ = True
+        original_args, original_kwargs = args, kwargs
+        if self._has_sensitive(args, kwargs):
+            args, kwargs = self._unwrap_args(args, kwargs)
+        try:
+            return super()._devlog_executor(fn, *args, **kwargs)
+        except BaseException as e:
+            self._on_error(fn, e, *original_args, **original_kwargs)
+
+    async def _async_devlog_executor(self, fn: FunctionType, *args: Any, **kwargs: Any) -> Any:
+        __tracebackhide__ = True
+        original_args, original_kwargs = args, kwargs
+        if self._has_sensitive(args, kwargs):
+            args, kwargs = self._unwrap_args(args, kwargs)
+        try:
+            return await super()._async_devlog_executor(fn, *args, **kwargs)
+        except BaseException as e:
+            self._on_error(fn, e, *original_args, **original_kwargs)
+
+    def _do_logging(self, fn: FunctionType, *args: Any, **kwargs: Any) -> None:
+        logger = self.get_logger(fn)
+        full_traceback = traceback.TracebackException(*sys.exc_info(), capture_locals=self.capture_locals)
+        custom_traceback = list(LoggingDecorator.get_stack_summary(
+            self.include_decorator, capture_locals=self.capture_locals)
+        )
+
+        # exclude all the stack trace that are in this module
+        for frame in full_traceback.stack:
+            if not LoggingDecorator._is_internal_file(frame.filename) or self.include_decorator:
+                custom_traceback.append(frame)
+
+        full_traceback.stack = traceback.StackSummary(custom_traceback)
+
+        extra = {self.callable_format_variable: fn,
+                 self.exception_format_variable: "".join(list(full_traceback.format(chain=True))).strip()}
+
+        msg = self.build_msg(fn, fn_args=args, fn_kwargs=kwargs, **extra)
+
+        self.log(logger, self.log_level, msg)
+
+    def _on_error(self, fn: FunctionType, exception: BaseException, *args: Any, **kwargs: Any) -> None:
+        __tracebackhide__ = True
+        if issubclass(exception.__class__, self.on_exceptions) and not hasattr(exception, "_devlog_logged"):
+            self._do_logging(fn, *args, **kwargs)
+            exception._devlog_logged = True
+        if self.reraise:
+            raise
+
+
+# Register this file as internal
+LoggingDecorator._internal_files.add(__file__)

devlog/sanitize.py

@@ -0,0 +1,139 @@
+import operator
+from typing import Any
+
+
+class Sensitive:
+    """Transparent proxy that marks a value for redaction in devlog logs only.
+
+    The wrapped value passes through to functions unchanged — all attribute access,
+    operators, iteration, etc. are delegated to the real value. Redaction only
+    happens when devlog formats log messages.
+
+    Usage:
+        password = Sensitive("hunter2")
+        login(password)  # function receives "hunter2" normally
+        # but devlog logs show: login(password='***')
+    """
+
+    __slots__ = ('_devlog_value', '_devlog_mask')
+
+    def __init__(self, value: Any, mask: str = "***"):
+        object.__setattr__(self, '_devlog_value', value)
+        object.__setattr__(self, '_devlog_mask', mask)
+
+    @property
+    def real_value(self) -> Any:
+        return object.__getattribute__(self, '_devlog_value')
+
+    @property
+    def mask(self) -> str:
+        return object.__getattribute__(self, '_devlog_mask')
+
+    # --- transparent proxy ---
+    def __getattr__(self, name: str) -> Any:
+        return getattr(object.__getattribute__(self, '_devlog_value'), name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        setattr(object.__getattribute__(self, '_devlog_value'), name, value)
+
+    def __delattr__(self, name: str) -> None:
+        delattr(object.__getattribute__(self, '_devlog_value'), name)
+
+    def __str__(self) -> str:
+        return str(object.__getattribute__(self, '_devlog_value'))
+
+    def __repr__(self) -> str:
+        return repr(object.__getattribute__(self, '_devlog_value'))
+
+    def __bool__(self) -> bool:
+        return bool(object.__getattribute__(self, '_devlog_value'))
+
+    def __len__(self) -> int:
+        return len(object.__getattribute__(self, '_devlog_value'))
+
+    def __iter__(self):
+        return iter(object.__getattribute__(self, '_devlog_value'))
+
+    def __contains__(self, item: Any) -> bool:
+        return item in object.__getattribute__(self, '_devlog_value')
+
+    def __getitem__(self, key: Any) -> Any:
+        return object.__getattribute__(self, '_devlog_value')[key]
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        object.__getattribute__(self, '_devlog_value')[key] = value
+
+    def __delitem__(self, key: Any) -> None:
+        del object.__getattribute__(self, '_devlog_value')[key]
+
+    def __eq__(self, other: Any) -> bool:
+        val = object.__getattribute__(self, '_devlog_value')
+        other_val = other.real_value if isinstance(other, Sensitive) else other
+        return val == other_val
+
+    def __hash__(self) -> int:
+        return hash(object.__getattribute__(self, '_devlog_value'))
+
+    def __lt__(self, other: Any) -> bool:
+        val = object.__getattribute__(self, '_devlog_value')
+        other_val = other.real_value if isinstance(other, Sensitive) else other
+        return val < other_val
+
+    def __le__(self, other: Any) -> bool:
+        val = object.__getattribute__(self, '_devlog_value')
+        other_val = other.real_value if isinstance(other, Sensitive) else other
+        return val <= other_val
+
+    def __gt__(self, other: Any) -> bool:
+        val = object.__getattribute__(self, '_devlog_value')
+        other_val = other.real_value if isinstance(other, Sensitive) else other
+        return val > other_val
+
+    def __ge__(self, other: Any) -> bool:
+        val = object.__getattribute__(self, '_devlog_value')
+        other_val = other.real_value if isinstance(other, Sensitive) else other
+        return val >= other_val
+
+    def __add__(self, other: Any) -> Any:
+        val = object.__getattribute__(self, '_devlog_value')
+        other_val = other.real_value if isinstance(other, Sensitive) else other
+        return val + other_val
+
+    def __radd__(self, other: Any) -> Any:
+        val = object.__getattribute__(self, '_devlog_value')
+        return other + val
+
+    def __mul__(self, other: Any) -> Any:
+        val = object.__getattribute__(self, '_devlog_value')
+        other_val = other.real_value if isinstance(other, Sensitive) else other
+        return val * other_val
+
+    def __rmul__(self, other: Any) -> Any:
+        val = object.__getattribute__(self, '_devlog_value')
+        return other * val
+
+    def __int__(self) -> int:
+        return int(object.__getattribute__(self, '_devlog_value'))
+
+    def __float__(self) -> float:
+        return float(object.__getattribute__(self, '_devlog_value'))
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return object.__getattribute__(self, '_devlog_value')(*args, **kwargs)
+
+
+def unwrap_sensitive(value: Any) -> Any:
+    """Unwrap a Sensitive value to its real value, or return as-is."""
+    if isinstance(value, Sensitive):
+        return value.real_value
+    return value
+
+
+def format_value(value: Any, param_name: str = "",
+                 sanitize_params: set = None) -> str:
+    """Format a value for log display, applying redaction as needed."""
+    if isinstance(value, Sensitive):
+        return object.__getattribute__(value, '_devlog_mask')
+    if sanitize_params and param_name in sanitize_params:
+        return "***"
+    return repr(value)