python-corekit 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/log_monitor/service.py

@@ -11,6 +11,7 @@ per container so a crash loop cannot become a restart loop.
 """
 
 import re
+import shlex
 import signal
 import subprocess
 import threading
@@ -51,7 +52,7 @@ class LogMonitor(Watchdog):
         config_path: str | None = None,
         config: LogMonitorConfig | None = None,
         notification_service: BaseNotificationService | None = None,
-        enforce_label: bool = False,
+        enforce_label: bool = True,
         max_workers: int | None = None,
         docker_host: str | None = None,
         handle_signals: bool = False,
@@ -61,6 +62,7 @@ class LogMonitor(Watchdog):
         :param config: an already-built configuration, instead of a path.
         :param notification_service: where notifications go; logs by default.
         :param enforce_label: only act on containers carrying the managed label.
+            On by default, matching Watchdog.
         :param handle_signals: install SIGTERM and SIGINT handlers. Off by
             default because installing them is process-global and only the
             program's entry point should decide that; ``run()`` turns it on.
@@ -117,12 +119,31 @@ class LogMonitor(Watchdog):
         }
         return mapping.get(severity, NotificationType.INFO)
 
-    def _send_notification(self, message: str, severity: Severity) -> None:
-        """Send notification using the notification service"""
+    def _send_notification(
+        self,
+        message: str,
+        severity: Severity,
+        container_name: str,
+        throttle: float = 0,
+    ) -> bool:
+        """
+        Send one notification for a container, honoring its throttle.
+
+        This is the only delivery path. A YAML notify action and a rule's
+        ``send_notification`` flag both come through here, so the throttle
+        cannot be recorded in one place and ignored in another.
+        """
+        last_notify = self.last_notify_times.get(container_name, 0.0)
+        if throttle and time.time() - last_notify < throttle:
+            self.debug(f"Notification throttled for {container_name}")
+            return False
+
+        self.last_notify_times[container_name] = time.time()
         notification = Notification(
             message=message, type=self._severity_to_notification_type(severity), meta={"source": "LogMonitor"}
         )
         self._notification_service.notify(notification)
+        return True
 
     def check_rate_limit(self, action_type: ActionType) -> bool:
         """Check if action is within rate limits"""
@@ -145,14 +166,17 @@ class LogMonitor(Watchdog):
         message = action.message.format(container=container_name, text=matched_text)
         self.info(f"[LogAction] {message}")
 
-    def _execute_notify_action(self, action: NotifyAction, container_name: str) -> None:
-        """Execute notify action - check throttle only (actual notification sent separately)"""
-        # Check throttle
-        last_notify = self.last_notify_times.get(container_name, 0.0)
-        if time.time() - last_notify < action.throttle:
-            self.debug(f"Notification throttled for {container_name}")
-            return
-        self.last_notify_times[container_name] = time.time()
+    def _execute_notify_action(
+        self,
+        action: NotifyAction,
+        container_name: str,
+        matched_text: str,
+        severity: Severity,
+        rule_name: str,
+    ) -> None:
+        """Deliver a notification, applying this action's throttle."""
+        message = f"*{rule_name}* in `{container_name}`\n```{matched_text.strip()}```"
+        self._send_notification(message, severity, container_name, throttle=action.throttle)
 
     def _execute_restart_action(self, action: RestartContainerAction, container_name: str) -> None:
         """Execute restart action - delegate to Watchdog parent"""
@@ -172,42 +196,51 @@ class LogMonitor(Watchdog):
             self.info(f"Waiting {action.delay}s before restarting {container_name}")
             time.sleep(action.delay)
 
-        try:
-            # Delegate to parent Watchdog method
-            container = self._client.containers.get(container_name)
-            container.restart()
+        if self.restart_container_by_name(container_name):
             self.restart_counts[container_name].append(time.time())
-            self.info(f"Restarted container: {container_name}")
-        except NotFound:
-            self.error(f"Container '{container_name}' not found")
-        except APIError as e:
-            self.error(f"Failed to restart {container_name}: {e}")
 
     def _execute_pause_action(self, action: PauseContainerAction, container_name: str) -> None:
         """Execute pause action - delegate to Watchdog parent"""
         self.pause_container_by_name(container_name)
 
     def _execute_command_action(self, action: ExecuteCommandAction, container_name: str) -> None:
-        """Execute shell command action"""
-        command = action.command.format(container=container_name)
+        """
+        Run a command as an argument list. The config string is not a shell.
+        """
+        try:
+            argv = [part.format(container=container_name) for part in shlex.split(action.command)]
+        except ValueError as exc:
+            self.error(f"Invalid command for {container_name}: {exc}")
+            return
+        if not argv:
+            self.error(f"Empty command for {container_name}")
+            return
         try:
             result = subprocess.run(
-                command,
-                shell=True,
+                argv,
+                shell=False,
                 capture_output=True,
                 text=True,
-                timeout=30,  # 30 second timeout for safety
+                timeout=30,
             )
+            rendered = " ".join(argv)
             if result.returncode == 0:
-                self.info(f"Executed: {command}\nOutput: {result.stdout}")
+                self.info(f"Executed: {rendered}\nOutput: {result.stdout}")
             else:
-                self.error(f"Command failed: {command}\nError: {result.stderr}")
+                self.error(f"Command failed: {rendered}\nError: {result.stderr}")
         except subprocess.TimeoutExpired:
-            self.error(f"Command timed out: {command}")
+            self.error(f"Command timed out: {action.command}")
         except Exception as e:
             self.error(f"Failed to execute command: {e}")
 
-    def execute_action(self, action: Action, container_name: str, matched_text: str = "") -> None:
+    def execute_action(
+        self,
+        action: Action,
+        container_name: str,
+        matched_text: str = "",
+        severity: Severity = Severity.INFO,
+        rule_name: str = "",
+    ) -> None:
         """Execute configured actions by delegating to specific action handlers"""
         action_type = action.type
 
@@ -221,7 +254,7 @@ class LogMonitor(Watchdog):
         if action_type is ActionType.LOG:
             self._execute_log_action(action, container_name, matched_text)
         elif action_type is ActionType.NOTIFY:
-            self._execute_notify_action(action, container_name)
+            self._execute_notify_action(action, container_name, matched_text, severity, rule_name)
         elif action_type is ActionType.RESTART_CONTAINER:
             self._execute_restart_action(action, container_name)
         elif action_type is ActionType.PAUSE_CONTAINER:
@@ -246,14 +279,20 @@ class LogMonitor(Watchdog):
                 else:
                     self.info(log_message)
 
-                # Execute actions
-                for action in rule.actions:
-                    self.execute_action(action, container_name, line)
-
-                # Send notification if configured
-                if rule.send_notification:
-                    message = f"*{rule.name}* in `{container_name}`\n```{line.strip()}```"
-                    self._send_notification(message, rule.severity)
+                # A notify flag is the same delivery path as a notify action.
+                # Do not send beside it: that path used to ignore the throttle.
+                actions = list(rule.actions)
+                if rule.send_notification and not any(action.type is ActionType.NOTIFY for action in actions):
+                    actions.append(NotifyAction())
+
+                for action in actions:
+                    self.execute_action(
+                        action,
+                        container_name,
+                        line,
+                        severity=rule.severity,
+                        rule_name=rule.name,
+                    )
 
     # FIXME: does this actually make more sense being part of watchdog?
     def monitor_container(self, container_name: str, rules: list[Rule]) -> None:

corekit/notifications/base.py

@@ -8,13 +8,15 @@ Subclass ``BaseNotificationService`` and implement ``_send``::
         Sends notifications by email.
         '''
 
-        def _send(self, message: str) -> None:
-            smtp.send(message)
+        def _send(self, notification: Notification) -> None:
+            smtp.send(notification.message, extra=notification.meta)
 
     service.notify(Notification(message="disk full", type=NotificationType.ERROR))
 
-Override ``_send``, not ``send``: ``notify`` formats the message and calls
-``_send``, so an override with any other name silently does nothing.
+Override ``_send``, not ``notify``, if you only want to replace the transport.
+``notify`` hands the whole ``Notification`` to ``_send``, including ``meta``.
+Events are a different job: they fan a payload out over Redis, they do not
+alert a person.
 """
 
 from corekit.notifications.models import Notification
@@ -36,16 +38,22 @@ class BaseNotificationService(Loggable):
         """
         Render a notification as the text a transport will send.
         """
-        return f"[{notification.type} Notification]: {notification.message}"
+        text = f"[{notification.type} Notification]: {notification.message}"
+        if notification.meta:
+            return f"{text} {notification.meta}"
+        return text
 
-    def _send(self, message: str) -> None:
+    def _send(self, notification: Notification) -> None:
         """
-        Deliver formatted text. Override this in a subclass.
+        Deliver a notification. Override this in a subclass.
+
+        The argument is the notification, not a preformatted string, so a
+        transport can use ``message``, ``type``, and ``meta``.
         """
-        self.warning(message)
+        self.warning(self._format(notification))
 
     def notify(self, notification: Notification) -> None:
         """
-        Format a notification and deliver it.
+        Hand a notification to the transport, including its meta.
         """
-        self._send(self._format(notification))
+        self._send(notification)

corekit/observability/__init__.py

@@ -16,8 +16,15 @@ are the same concern -- knowing what a running system is doing.
 
 from corekit.observability.benchmarkable import Benchmarkable
 from corekit.observability.loggable import Loggable
-from corekit.observability.request_context import BaseRequestContext
+from corekit.observability.request_context import BaseRequestContext, RequestContextFilter
 from corekit.observability.timing.split import Split
 from corekit.observability.timing.timer import Timer
 
-__all__ = ["BaseRequestContext", "Benchmarkable", "Loggable", "Split", "Timer"]
+__all__ = [
+    "BaseRequestContext",
+    "Benchmarkable",
+    "Loggable",
+    "RequestContextFilter",
+    "Split",
+    "Timer",
+]

corekit/observability/benchmarkable.py

@@ -1,12 +1,30 @@
+from typing import Any
+
 from corekit.observability.loggable import Loggable
+from corekit.observability.timing.split import Split
 from corekit.observability.timing.timer import Timer
 
 
 class Benchmarkable(Loggable):
-    def __init__(self) -> None:
-        super().__init__()
+    """
+    ``Loggable`` plus split timing.
+
+    ``__init__`` forwards ``*args``/``**kwargs`` the same way ``Loggable``
+    does, so a service can sit in a cooperative ``super()`` chain without
+    this class swallowing the arguments the next base expects.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
         self._timing = Timer()
 
-    def timing(self, split_name: str | None = None) -> None:
-        split_message = str(self._timing.split(split_name=split_name))
-        self.info(split_message)
+    def timing(self, split_name: str | None = None) -> Split:
+        """
+        Log the time since the last split and return it.
+
+        The log line is unchanged. The return value is for a caller that
+        wants the numbers without parsing that line.
+        """
+        split = self._timing.split(split_name=split_name)
+        self.info(str(split))
+        return split

corekit/observability/loggable.py

@@ -1,6 +1,8 @@
 import logging
 from typing import Any
 
+from corekit.observability.request_context import RequestContextFilter
+
 
 class Loggable:
     """
@@ -8,10 +10,16 @@ class Loggable:
 
     Accepts and ignores ``*args``/``**kwargs`` so it can sit anywhere in a
     cooperative ``super().__init__()`` chain.
+
+    The logger name is the class name, not ``module.Class``. Consuming
+    projects filter on that name; renaming it is a log-config change, not a
+    local cleanup. Request context is attached as record attributes instead,
+    so a formatter can include it without renaming the logger.
     """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         self.logger = logging.getLogger(self.__class__.__name__)
+        _attach_request_context(self.logger)
 
     def debug(self, message: str, **kwargs: Any) -> None:
         self.logger.debug(message, **kwargs)
@@ -27,3 +35,16 @@ class Loggable:
 
     def exception(self, message: str, **kwargs: Any) -> None:
         self.logger.exception(message, **kwargs)
+
+
+def _attach_request_context(logger: logging.Logger) -> None:
+    """
+    Attach the request-context filter once per logger name.
+
+    Loggers are process-global and keyed by name, so every instance of a
+    class shares one. Adding the filter again would stamp the same fields
+    twice.
+    """
+    if any(isinstance(existing, RequestContextFilter) for existing in logger.filters):
+        return
+    logger.addFilter(RequestContextFilter())

corekit/observability/request_context.py

@@ -27,13 +27,14 @@ Each subclass gets its own storage, so one application's context cannot be read
 through another's class.
 """
 
+import logging
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
-from typing import Any, Iterator, Self
+from typing import Any, ClassVar, Iterator, Self
 
 from pydantic import BaseModel
 
-__all__ = ["BaseRequestContext"]
+__all__ = ["BaseRequestContext", "RequestContextFilter"]
 
 
 class BaseRequestContext(BaseModel):
@@ -45,12 +46,18 @@ class BaseRequestContext(BaseModel):
     between them leaks the context into whatever runs next on that task.
     """
 
+    #: Subclasses that own storage. The logging filter walks this rather than
+    #: guessing which application's context class is in use.
+    _known_subclasses: ClassVar[list[type["BaseRequestContext"]]] = []
+
     def __init_subclass__(cls, **kwargs: Any) -> None:
         """
         Give every subclass its own ContextVar.
         """
         super().__init_subclass__(**kwargs)
         cls._context_var = ContextVar(f"{cls.__module__}.{cls.__name__}", default=None)
+        if cls not in BaseRequestContext._known_subclasses:
+            BaseRequestContext._known_subclasses.append(cls)
 
     @classmethod
     def _var(cls) -> ContextVar[Any]:
@@ -133,3 +140,49 @@ class BaseRequestContext(BaseModel):
             yield type(self).current()
         finally:
             type(self).deactivate(token)
+
+
+class RequestContextFilter(logging.Filter):
+    """
+    Stamp the active request context onto each log record.
+
+    The message is left alone, so existing log lines and anything that
+    matches them stay stable. Fields land on the record for a formatter
+    that opts in: ``%(request_context)s`` is a compact summary, and
+    ``request_context_fields`` is the dumped model. Both are always set,
+    to an empty string and an empty dict when nothing is active, so a
+    format string that names them does not raise.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        fields: dict[str, Any] = {}
+        parts: list[str] = []
+        for cls in BaseRequestContext._known_subclasses:
+            current = cls.current()
+            if current is None:
+                continue
+            dumped = _dump_context(current)
+            if not dumped:
+                continue
+            fields[cls.__name__] = dumped
+            rendered = ", ".join(f"{key}={value}" for key, value in dumped.items())
+            parts.append(f"{cls.__name__}({rendered})")
+
+        record.request_context = " ".join(parts)
+        record.request_context_fields = fields
+        return True
+
+
+def _dump_context(context: BaseRequestContext) -> dict[str, Any]:
+    """
+    JSON-safe fields, or stringified values if a field will not dump.
+    """
+    try:
+        dumped = context.model_dump(mode="json")
+    except Exception:
+        dumped = {key: getattr(context, key, None) for key in type(context).model_fields}
+    return {key: value if _is_log_safe(value) else str(value) for key, value in dumped.items()}
+
+
+def _is_log_safe(value: Any) -> bool:
+    return value is None or isinstance(value, (str, int, float, bool))

corekit/observability/timing/timer.py

@@ -6,7 +6,9 @@ from corekit.observability.timing.split import Split
 
 class Timer:
     def __init__(self, precision: int = DEFAULT_PRECISION) -> None:
-        _time = time.time()
+        # perf_counter is monotonic. time.time() can step backwards, which
+        # makes a split look negative for no reason the caller can act on.
+        _time = time.perf_counter()
         self.start = _time
         self.latest = _time
         self.num = 0
@@ -17,7 +19,7 @@ class Timer:
         return round(value, self.precision)
 
     def split(self, split_name: str | None = None) -> Split:
-        _time = time.time()
+        _time = time.perf_counter()
         self.num += 1
         split = Split(
             num=self.num,

corekit/registry/__init__.py

@@ -12,6 +12,6 @@ duplicates. Reach for it when position is what matters and no name is needed.
 """
 
 from corekit.registry.ordered import OrderedRegistry
-from corekit.registry.registry import SmartRegistry
+from corekit.registry.registry import SmartRegistry, normalize_key
 
-__all__ = ["OrderedRegistry", "SmartRegistry"]
+__all__ = ["OrderedRegistry", "SmartRegistry", "normalize_key"]

corekit/registry/registry.py

@@ -1,11 +1,17 @@
+import logging
 import re
 from typing import Any, Iterator
 
+from corekit.config import get_settings
+
 REPLACEMENT_CHAR = "-"
 NORMALIZATION_PATTERN = re.compile(r"[\s_-]+")
 # Split CamelCase into words: "HTTPServerError" -> "HTTP-Server-Error".
 CAMEL_BOUNDARY_PATTERN = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
 
+_logger = logging.getLogger("SmartRegistry")
+_MISSING = object()
+
 
 class SmartRegistry:
     """
@@ -31,19 +37,33 @@ class SmartRegistry:
         """
         Retrieve an item from the registry using a normalized key.
         """
-        return self.__registry__[self.__normalize_key__(key)]
+        return self.__registry__[normalize_key(key)]
 
     def __setitem__(self, key: str, value: Any) -> None:
         """
         Store an item in the registry with a normalized key.
-        """
-        self.__registry__[self.__normalize_key__(key)] = value
+
+        A second write to the same normalized key used to replace the first
+        with no signal. That drops a handler that spelled the same name a
+        different way. The replacement is still allowed so an intentional
+        update works; it is warned, and refused when ``strict_mode`` is on.
+        """
+        normalized = normalize_key(key)
+        existing = self.__registry__.get(normalized, _MISSING)
+        if existing is not _MISSING and existing is not value:
+            if _strict_mode():
+                raise ValueError(
+                    f"Registry already contains {normalized!r}. "
+                    f"strict_mode refuses a second registration under the same key."
+                )
+            _logger.warning(f"Overwriting registry key {normalized!r}")
+        self.__registry__[normalized] = value
 
     def __delitem__(self, key: str) -> None:
         """
         Remove an item from the registry.
         """
-        del self.__registry__[self.__normalize_key__(key)]
+        del self.__registry__[normalize_key(key)]
 
     def __iter__(self) -> Iterator[str]:
         """
@@ -73,7 +93,7 @@ class SmartRegistry:
         """
         Check if a normalized key exists in the registry.
         """
-        return self.__normalize_key__(key) in self.__registry__
+        return normalize_key(key) in self.__registry__
 
     def __str__(self) -> str:
         """
@@ -114,21 +134,42 @@ class SmartRegistry:
         self.__registry__ = state
 
     @staticmethod
-    def __normalize_key__(key: str) -> str:
+    def normalize_key(key: str) -> str:
         """
         Reduce a key to a canonical hyphenated form.
 
-        Word boundaries are taken from CamelCase as well as from whitespace,
-        underscores and hyphens, so ``"GreetingHandler"``, ``"greeting_handler"``
-        and ``"Greeting Handler"`` all normalize to ``"greeting-handler"``.
-        Without the CamelCase step a class registered under its ``__name__``
-        could not be found by the snake_case name a caller would naturally type.
+        Public so callers do not have to reach for the old private name.
+        ``__normalize_key__`` remains as an alias.
         """
-        spaced = CAMEL_BOUNDARY_PATTERN.sub(REPLACEMENT_CHAR, key.strip())
-        return NORMALIZATION_PATTERN.sub(REPLACEMENT_CHAR, spaced.lower()).strip(REPLACEMENT_CHAR)
+        return normalize_key(key)
+
+    # Kept so existing callers, including ThreadLocalRegistry and tests, keep
+    # working. New code should call ``normalize_key``.
+    __normalize_key__ = staticmethod(normalize_key)
 
     def get(self, key: str, fallback: Any = None) -> Any:
         """
         Safely retrieve an item from the registry with an optional fallback.
         """
-        return self.__registry__.get(self.__normalize_key__(key), fallback)
+        return self.__registry__.get(normalize_key(key), fallback)
+
+
+def _strict_mode() -> bool:
+    """
+    Whether a colliding key should be refused.
+    """
+    return get_settings().standards.strict_mode
+
+
+def normalize_key(key: str) -> str:
+    """
+    Reduce a key to a canonical hyphenated form.
+
+    Word boundaries are taken from CamelCase as well as from whitespace,
+    underscores and hyphens, so ``"GreetingHandler"``, ``"greeting_handler"``
+    and ``"Greeting Handler"`` all normalize to ``"greeting-handler"``.
+    Without the CamelCase step a class registered under its ``__name__``
+    could not be found by the snake_case name a caller would naturally type.
+    """
+    spaced = CAMEL_BOUNDARY_PATTERN.sub(REPLACEMENT_CHAR, key.strip())
+    return NORMALIZATION_PATTERN.sub(REPLACEMENT_CHAR, spaced.lower()).strip(REPLACEMENT_CHAR)

corekit/schemas/enum.py

@@ -18,7 +18,7 @@ class ValidatingEnum(Enum):
     def validate_and_create(cls, value: Any) -> "ValidatingEnum":
         if cls.is_member(value):
             return cls(value)
-        raise ValueError(f"{cls.__name__} does not contain {cls}")
+        raise ValueError(f"{cls.__name__} does not contain {value!r}")
 
     @classmethod
     def get_all_members(cls) -> list["ValidatingEnum"]:
@@ -32,6 +32,15 @@ class ValidatingEnum(Enum):
 
 
 class StringEnum(str, ValidatingEnum):
+    """
+    String-valued enum that stringifies to its value.
+
+    Plain ``(str, Enum)`` members compare equal to their value but ``str()`` /
+    f-strings still render as ``ClassName.MEMBER``. Override that so DB defaults,
+    status comparisons, and log lines get ``"pending"`` rather than
+    ``"AccountRequestStatus.PENDING"``.
+    """
+
     @classmethod
     def from_string(cls, value: str) -> "StringEnum":
         """
@@ -39,6 +48,12 @@ class StringEnum(str, ValidatingEnum):
         """
         return cls.validate_and_create(value)
 
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __format__(self, format_spec: str) -> str:
+        return self.value.__format__(format_spec)
+
 
 class IntegerEnum(int, ValidatingEnum):
     @classmethod
@@ -47,3 +62,9 @@ class IntegerEnum(int, ValidatingEnum):
         Convert an integer to the corresponding enum member.
         """
         return cls.validate_and_create(value)
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __format__(self, format_spec: str) -> str:
+        return self.value.__format__(format_spec)

corekit/schemas/types.py

@@ -1,5 +1,5 @@
 from datetime import date, datetime
-from typing import Any, Sequence
+from typing import Any, Awaitable, Callable, Coroutine, Sequence
 
 # ========== Primitive Types ==========
 Number = int | float
@@ -38,3 +38,8 @@ UnknownSet = set[Any]
 
 # ========== Date Types ==========
 ArbitraryDate = date | datetime
+
+# ========== Function Types ==========
+AsyncFunction = Callable[..., Awaitable[Any] | Coroutine[Any, Any, Any]]
+SyncFunction = Callable[..., Any]
+ArbitraryFunction = AsyncFunction | SyncFunction

corekit/serialization/__init__.py

@@ -10,10 +10,12 @@ Set a key with ``COREKIT_SERIALIZATION__KEY`` to use an executing engine.
 """
 
 from corekit.serialization.enum import SerializerEngine
+from corekit.serialization.pickle_file import PickleFileManager
 from corekit.serialization.serializable import Serializable
 from corekit.serialization.serializer import Serializer, SignatureError, UnsafeEngineError
 
 __all__ = [
+    "PickleFileManager",
     "Serializable",
     "Serializer",
     "SerializerEngine",