pythagoras 0.24.2__py3-none-any.whl → 0.24.4__py3-none-any.whl

pythagoras/_040_logging_code_portals/logging_portal_core_classes.py

@@ -5,10 +5,10 @@ import traceback
 from typing import Callable, Any
 
 import pandas as pd
-# from parameterizable import register_parameterizable_class
+from parameterizable import NotPicklableClass
 from persidict import PersiDict, KEEP_CURRENT, Joker
 
-from .._010_basic_portals import NotPicklable, get_active_portal
+from .._010_basic_portals import get_active_portal
 from .._010_basic_portals.basic_portal_core_classes import (
     _describe_persistent_characteristic, _describe_runtime_characteristic)
 
@@ -32,6 +32,18 @@ from .._800_signatures_and_converters.random_signatures import (
 
 
 class LoggingFn(StorableFn):
+    """A function wrapper that logs executions, outputs, events, and crashes.
+
+    LoggingFn wraps a callable and, when executed within a LoggingCodePortal,
+    records execution attempts, results, captured stdout/stderr, raised
+    exceptions, and custom events. It also supports an excessive_logging mode
+    that enables storing rich per-call artifacts.
+
+    Attributes:
+        _auxiliary_config_params_at_init (dict): Internal configuration store
+            inherited from StorableFn. Includes the 'excessive_logging' flag
+            when provided.
+    """
 
     # _excessive_logging_at_init: bool | Joker
 
@@ -40,6 +52,19 @@ class LoggingFn(StorableFn):
             , excessive_logging: bool|Joker = KEEP_CURRENT
             , portal: LoggingCodePortal | None = None
             ):
+        """Initialize a LoggingFn wrapper.
+
+        Args:
+            fn: A callable to wrap or a string with a function's source code.
+            excessive_logging: If True, capture detailed per-execution
+                artifacts (attempt context, outputs, results). If KEEP_CURRENT,
+                will inherit the setting from another LoggingFn when cloning.
+            portal: Optional LoggingCodePortal to bind this function to. If
+                omitted, uses the active portal during execution.
+
+        Raises:
+            TypeError: If excessive_logging is not a bool or Joker.
+        """
         super().__init__(fn=fn, portal=portal)
 
         if not isinstance(excessive_logging, (bool, Joker)):
@@ -56,15 +81,43 @@ class LoggingFn(StorableFn):
 
     @property
     def excessive_logging(self) -> bool:
+        """Whether rich per-execution logging is enabled for this function.
+
+        Returns:
+            bool: True if excessive logging is enabled for this function (from
+            its own config or inherited via the portal); False otherwise.
+        """
         value = self._get_config_setting("excessive_logging", self.portal)
         return bool(value)
 
 
     def get_signature(self, arguments:dict) -> LoggingFnCallSignature:
+        """Create a call signature for this function and the given arguments.
+
+        Args:
+            arguments: A mapping of keyword arguments for the call. Values may
+                be raw or ValueAddr; they will be normalized and packed.
+
+        Returns:
+            LoggingFnCallSignature: A signature object uniquely identifying
+            the combination of function and arguments.
+        """
         return LoggingFnCallSignature(self, arguments)
 
 
     def execute(self,**kwargs):
+        """Execute the wrapped function and log artifacts via the portal.
+
+        Args:
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Returns:
+            Any: The result returned by the wrapped function.
+
+        Side Effects:
+            - Registers an execution attempt and, if enabled, captures
+              stdout/stderr and stores the result and output.
+        """
         with self.portal:
             packed_kwargs = KwArgs(**kwargs).pack()
             fn_call_signature = self.get_signature(packed_kwargs)
@@ -76,6 +129,12 @@ class LoggingFn(StorableFn):
 
     @property
     def portal(self) -> LoggingCodePortal:
+        """The LoggingCodePortal associated with this function.
+
+        Returns:
+            LoggingCodePortal: The portal used for storage and logging during
+            execution.
+        """
         return super().portal
 
 
@@ -109,6 +168,12 @@ class   LoggingFnCallSignature:
 
     @property
     def portal(self):
+        """Portal associated with the underlying function.
+
+        Returns:
+            LoggingCodePortal: The portal used to store and retrieve logging
+            artifacts for this call signature.
+        """
         return self.fn.portal
 
 
@@ -146,6 +211,11 @@ class   LoggingFnCallSignature:
 
     @property
     def fn(self) -> LoggingFn:
+        """Resolve and cache the wrapped LoggingFn instance.
+
+        Returns:
+            LoggingFn: The function associated with this call signature.
+        """
         if not hasattr(self, "_fn_cache") or self._fn_cache is None:
             self._fn_cache = self.fn_addr.get(expected_type=LoggingFn)
         return self._fn_cache
@@ -153,6 +223,11 @@ class   LoggingFnCallSignature:
 
     @property
     def fn_name(self) -> str:
+        """Name of the wrapped function.
+
+        Returns:
+            str: The function's name, cached after first access.
+        """
         if not hasattr(self, "_fn_name_cache") or self._fn_name_cache is None:
             self._fn_name_cache = self.fn.name
         return self._fn_name_cache
@@ -160,16 +235,31 @@ class   LoggingFnCallSignature:
 
     @property
     def fn_addr(self) -> ValueAddr:
+        """Address of the wrapped LoggingFn in the portal storage.
+
+        Returns:
+            ValueAddr: The persisted address pointing to the LoggingFn.
+        """
         return self._fn_addr
 
 
     @property
     def kwargs_addr(self) -> ValueAddr:
+        """Address of the packed keyword arguments in portal storage.
+
+        Returns:
+            ValueAddr: The persisted address pointing to the packed kwargs.
+        """
         return self._kwargs_addr
 
 
     @property
     def packed_kwargs(self) -> PackedKwArgs:
+        """Packed keyword arguments for this call signature.
+
+        Returns:
+            PackedKwArgs: The packed kwargs, fetched from storage if not cached.
+        """
         if (not hasattr(self,"_packed_kwargs_cache")
                 or self._packed_kwargs_cache is None):
             with self.portal:
@@ -180,10 +270,21 @@ class   LoggingFnCallSignature:
 
     @property
     def excessive_logging(self) -> bool:
+        """Whether excessive logging is enabled for the underlying function.
+
+        Returns:
+            bool: True if excessive logging is enabled, False otherwise.
+        """
         return self.fn.excessive_logging
 
 
     def __hash_signature_descriptor__(self) -> str:
+        """Descriptor string contributing to the address hash.
+
+        Returns:
+            str: A lowercase string combining the function name and this class
+            name, used as part of the address hashing scheme.
+        """
         descriptor = self.fn_name
         descriptor += "_" + self.__class__.__name__
         descriptor = descriptor.lower()
@@ -191,11 +292,21 @@ class   LoggingFnCallSignature:
 
 
     def execute(self) -> Any:
+        """Execute the underlying function with stored arguments.
+
+        Returns:
+            Any: The function's return value.
+        """
         return self.fn.execute(**self.packed_kwargs.unpack())
 
 
     @property
     def addr(self) -> ValueAddr:
+        """Address uniquely identifying this call signature.
+
+        Returns:
+            ValueAddr: Address of the LoggingFnCallSignature persisted in portal.
+        """
         if hasattr(self, "_addr_cache") and self._addr_cache is not None:
             return self._addr_cache
         with self.portal:
@@ -205,6 +316,11 @@ class   LoggingFnCallSignature:
 
     @property
     def execution_attempts(self) -> PersiDict:
+        """Timeline of execution attempts metadata for this call.
+
+        Returns:
+            PersiDict: Append-only JSON sub-dictionary keyed by timestamped IDs.
+        """
         with self.portal as portal:
             attempts_path = self.addr + ["attempts"]
             attempts = portal._run_history.json.get_subdict(attempts_path)
@@ -213,6 +329,11 @@ class   LoggingFnCallSignature:
 
     @property
     def last_execution_attempt(self) -> Any:
+        """Most recent execution attempt metadata, if any.
+
+        Returns:
+            Any: Latest attempt metadata dict, or None if no attempts exist.
+        """
         with self.portal:
             attempts = self.execution_attempts
             timeline = attempts.newest_values(1)
@@ -225,6 +346,11 @@ class   LoggingFnCallSignature:
 
     @property
     def execution_results(self) -> PersiDict:
+        """Timeline of execution results for this call.
+
+        Returns:
+            PersiDict: Append-only PKL sub-dictionary storing returned values.
+        """
         with self.portal as portal:
             results_path = self.addr + ["results"]
             results = portal._run_history.pkl.get_subdict(results_path)
@@ -233,6 +359,11 @@ class   LoggingFnCallSignature:
 
     @property
     def last_execution_result(self) -> Any:
+        """Most recent execution result, if any.
+
+        Returns:
+            Any: Latest return value, or None if no results exist.
+        """
         with self.portal:
             results = self.execution_results
             timeline = results.newest_values(1)
@@ -245,6 +376,11 @@ class   LoggingFnCallSignature:
 
     @property
     def execution_outputs(self) -> PersiDict:
+        """Timeline of captured stdout/stderr/logging output for this call.
+
+        Returns:
+            PersiDict: Append-only TXT sub-dictionary of captured output strings.
+        """
         with self.portal as portal:
             outputs_path = self.addr + ["outputs"]
             outputs = portal._run_history.txt.get_subdict(outputs_path)
@@ -253,6 +389,11 @@ class   LoggingFnCallSignature:
 
     @property
     def last_execution_output(self) -> Any:
+        """Most recent captured combined output, if any.
+
+        Returns:
+            Any: Latest captured output string, or None if no outputs exist.
+        """
         with self.portal:
             outputs = self.execution_outputs
             timeline = outputs.newest_values(1)
@@ -265,6 +406,11 @@ class   LoggingFnCallSignature:
 
     @property
     def crashes(self) -> PersiDict:
+        """Timeline of crashes (exceptions) observed during this call.
+
+        Returns:
+            PersiDict: Append-only JSON sub-dictionary of exception payloads.
+        """
         with self.portal as portal:
             crashes_path = self.addr + ["crashes"]
             crashes = portal._run_history.json.get_subdict(crashes_path)
@@ -273,6 +419,11 @@ class   LoggingFnCallSignature:
 
     @property
     def last_crash(self) -> Any:
+        """Most recent crash payload, if any.
+
+        Returns:
+            Any: Latest exception payload dict, or None if no crashes exist.
+        """
         with self.portal as portal:
             crashes = self.crashes
             timeline = crashes.newest_values(1)
@@ -285,6 +436,11 @@ class   LoggingFnCallSignature:
 
     @property
     def events(self) -> PersiDict:
+        """Timeline of user events emitted during this call.
+
+        Returns:
+            PersiDict: Append-only JSON sub-dictionary of event payloads.
+        """
         with self.portal as portal:
             events_path = self.addr + ["events"]
             events = portal._run_history.json.get_subdict(events_path)
@@ -293,6 +449,11 @@ class   LoggingFnCallSignature:
 
     @property
     def last_event(self) -> Any:
+        """Most recent user event payload, if any.
+
+        Returns:
+            Any: Latest event payload dict, or None if no events exist.
+        """
         with self.portal:
             events = self.events
             timeline = events.newest_values(1)
@@ -305,6 +466,12 @@ class   LoggingFnCallSignature:
 
     @property
     def execution_records(self) -> list[LoggingFnExecutionRecord]:
+        """All execution sessions derived from attempts for this call.
+
+        Returns:
+            list[LoggingFnExecutionRecord]: Records constructed from stored
+            attempt IDs for convenient access to artifacts per run session.
+        """
         with self.portal:
             result = []
             for k in self.execution_attempts:
@@ -313,15 +480,18 @@ class   LoggingFnCallSignature:
             return result
 
 
-class LoggingFnExecutionRecord(NotPicklable):
-    """ A record of one full function execution session.
+class LoggingFnExecutionRecord(NotPicklableClass):
+    """Record of a single function execution session.
 
-    It provides access to all information logged during the
-    execution session, which includes information about the execution context
-    (environment), function arguments, its output (everything that was
-    printed to stdout/stderr during the execution attempt), any crashes
-    (exceptions) and events fired, and an actual result of the execution
-    created by a 'return' statement within the function code.
+    Provides convenient accessors to all artifacts logged for one particular
+    execution of a LoggingFn: environment context, captured output, crashes,
+    events, and the returned result value.
+
+    Attributes:
+        call_signature (LoggingFnCallSignature): The function-call identity
+            this record belongs to.
+        session_id (str): Unique identifier for the execution session ("run_*"),
+            shared by all artifacts emitted during this run.
     """
     call_signature: LoggingFnCallSignature
     session_id: str
@@ -329,17 +499,34 @@ class LoggingFnExecutionRecord(NotPicklable):
             self
             , call_signature: LoggingFnCallSignature
             , session_id: str):
+        """Construct an execution record.
+
+        Args:
+            call_signature: The call signature the record is associated with.
+            session_id: The unique ID of the execution session.
+        """
         self.call_signature = call_signature
         self.session_id = session_id
 
 
     @property
     def portal(self):
+        """LoggingCodePortal used to resolve underlying artifacts.
+
+        Returns:
+            LoggingCodePortal: The portal associated with the call signature.
+        """
         return self.call_signature.portal
 
 
     @property
     def output(self) -> str|None:
+        """Combined stdout/stderr/logging output captured for the session.
+
+        Returns:
+            str | None: The captured text output, or None when no output
+            was recorded for this session.
+        """
         with self.portal:
             execution_outputs = self.call_signature.execution_outputs
             for k in execution_outputs:
@@ -350,6 +537,12 @@ class LoggingFnExecutionRecord(NotPicklable):
 
     @property
     def attempt_context(self)-> dict|None:
+        """Environment/context snapshot captured at attempt start.
+
+        Returns:
+            dict | None: The environment summary dict for this session, or
+            None if not present (e.g., excessive logging disabled).
+        """
         with self.portal:
             execution_attempts = self.call_signature.execution_attempts
             for k in execution_attempts:
@@ -360,6 +553,11 @@ class LoggingFnExecutionRecord(NotPicklable):
 
     @property
     def crashes(self) -> list[dict]:
+        """All exceptions recorded during the session.
+
+        Returns:
+            list[dict]: A list of exception payload dicts in chronological order.
+        """
         result = []
         with self.portal:
             crashes = self.call_signature.crashes
@@ -371,6 +569,11 @@ class LoggingFnExecutionRecord(NotPicklable):
 
     @property
     def events(self) -> list[dict]:
+        """All events recorded during the session.
+
+        Returns:
+            list[dict]: A list of event payload dicts in chronological order.
+        """
         result = []
         with self.portal:
             events = self.call_signature.events
@@ -382,6 +585,14 @@ class LoggingFnExecutionRecord(NotPicklable):
 
     @property
     def result(self)->Any:
+        """Return value produced by the function in this session.
+
+        Returns:
+            Any: The object returned by the wrapped function for the run.
+
+        Raises:
+            ValueError: If there is no stored result for this session ID.
+        """
         with self.portal:
             execution_results = self.call_signature.execution_results
             for k in execution_results:
@@ -392,7 +603,17 @@ class LoggingFnExecutionRecord(NotPicklable):
                 f"{self.call_signature.fn_name} execution results.")
 
 
-class LoggingFnExecutionFrame(NotPicklable):
+class LoggingFnExecutionFrame(NotPicklableClass):
+    """Context manager managing a single function execution with logging.
+
+    When used as a context, optionally captures stdout/stderr/logging,
+    registers attempt metadata, stores results and output, and routes
+    exceptions/events to both per-call artifacts and portal-level histories.
+
+    Attributes:
+        call_stack (list[LoggingFnExecutionFrame]): Class-level stack of active
+            frames (last item is the current execution frame).
+    """
     call_stack: list[LoggingFnExecutionFrame] = []
 
     session_id: str
@@ -404,6 +625,12 @@ class LoggingFnExecutionFrame(NotPicklable):
     context_used: bool
 
     def __init__(self, fn_call_signature: LoggingFnCallSignature):
+        """Initialize the execution frame for a specific function call.
+
+        Args:
+            fn_call_signature: The call signature identifying the function and
+                its (packed) arguments.
+        """
         with fn_call_signature.portal:
             self.session_id = "run_"+get_random_signature()
             self.fn_call_signature = fn_call_signature
@@ -421,40 +648,84 @@ class LoggingFnExecutionFrame(NotPicklable):
 
     @property
     def portal(self) -> LoggingCodePortal:
+        """Portal associated with the current execution frame.
+
+        Returns:
+            LoggingCodePortal: The portal used for logging within this frame.
+        """
         return self.fn.portal
 
 
     @property
     def fn(self) -> LoggingFn:
+        """The LoggingFn being executed in this frame.
+
+        Returns:
+            LoggingFn: The wrapped function object.
+        """
         return self.fn_call_signature.fn
 
 
     @property
     def fn_name(self) -> str:
+        """Name of the function being executed.
+
+        Returns:
+            str: The wrapped function's name.
+        """
         return self.fn_call_signature.fn_name
 
 
     @property
     def excessive_logging(self) -> bool:
+        """Whether the frame should capture detailed artifacts.
+
+        Returns:
+            bool: True if excessive logging is enabled for the function.
+        """
         return self.fn.excessive_logging
 
 
     @property
     def fn_addr(self) -> ValueAddr:
+        """Address of the wrapped function in storage.
+
+        Returns:
+            ValueAddr: The persisted address of the LoggingFn.
+        """
         return self.fn_call_signature.fn_addr
 
 
     @property
     def packed_args(self) -> PackedKwArgs:
+        """Packed keyword arguments used for this execution.
+
+        Returns:
+            PackedKwArgs: The packed argument mapping.
+        """
         return self.fn_call_signature.packed_kwargs
 
 
     @property
     def kwargs_addr(self) -> ValueAddr:
+        """Address of the packed arguments in storage.
+
+        Returns:
+            ValueAddr: The persisted address of the packed kwargs.
+        """
         return self.fn_call_signature.kwargs_addr
 
 
     def __enter__(self):
+        """Enter the execution frame context.
+
+        Performs sanity checks, enters the portal context, optionally starts
+        capturing output, pushes the frame onto the call stack, and registers
+        an execution attempt if excessive logging is enabled.
+
+        Returns:
+            LoggingFnExecutionFrame: This frame instance for use as a context var.
+        """
         assert not self.context_used, (
             "An instance of PureFnExecutionFrame can be used only once.")
         self.context_used = True
@@ -471,6 +742,10 @@ class LoggingFnExecutionFrame(NotPicklable):
 
 
     def _register_execution_attempt(self):
+        """Record an execution attempt with environment and source snapshot.
+
+        No-op when excessive logging is disabled.
+        """
         if not self.excessive_logging:
             return
         execution_attempts = self.fn_call_signature.execution_attempts
@@ -481,6 +756,14 @@ class LoggingFnExecutionFrame(NotPicklable):
 
 
     def _register_execution_result(self, result: Any):
+        """Store the function's return value into the results timeline.
+
+        Args:
+            result: The value returned by the wrapped function.
+
+        Notes:
+            No-op when excessive logging is disabled.
+        """
         if not self.excessive_logging:
             return
         execution_results = self.fn_call_signature.execution_results
@@ -489,6 +772,17 @@ class LoggingFnExecutionFrame(NotPicklable):
 
 
     def __exit__(self, exc_type, exc_value, trace_back):
+        """Exit the execution frame context.
+
+        Ensures the current exception (if any) is logged, finalizes output
+        capture and stores it, pops the frame from the call stack, and exits
+        the underlying portal context.
+
+        Args:
+            exc_type: Exception class raised within the context, if any.
+            exc_value: Exception instance raised within the context, if any.
+            trace_back: Traceback object associated with the exception, if any.
+        """
         log_exception()
         if isinstance(self.output_capturer, OutputCapturer):
             self.output_capturer.__exit__(exc_type, exc_value, traceback)
@@ -536,6 +830,22 @@ class LoggingCodePortal(DataPortal):
             , p_consistency_checks: float|Joker = KEEP_CURRENT
             , excessive_logging: bool|Joker = KEEP_CURRENT
             ):
+        """Construct a LoggingCodePortal.
+
+        Args:
+            root_dict: PersiDict instance or filesystem path serving as the
+                storage root. When None, a default in-memory or configured
+                PersiDict is used by the base DataPortal.
+            p_consistency_checks: Probability [0..1] to run consistency checks
+                on storage operations; KEEP_CURRENT inherits existing setting.
+            excessive_logging: If True, functions executed via this portal will
+                store detailed artifacts (attempts/results/outputs). If
+                KEEP_CURRENT, the setting is inherited when cloning or
+                otherwise unspecified.
+
+        Raises:
+            TypeError: If excessive_logging is not a bool or Joker.
+        """
         super().__init__(root_dict=root_dict
             , p_consistency_checks=p_consistency_checks)
         del root_dict
@@ -577,17 +887,35 @@ class LoggingCodePortal(DataPortal):
 
 
     def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the portal context, ensuring any active exception is logged.
+
+        Args:
+            exc_type: Exception class raised within the portal context, if any.
+            exc_val: Exception instance, if any.
+            exc_tb: Traceback object, if any.
+        """
         log_exception()
         super().__exit__(exc_type, exc_val, exc_tb)
 
 
     @property
     def excessive_logging(self) -> bool:
+        """Whether this portal captures detailed per-call artifacts.
+
+        Returns:
+            bool: True if excessive logging is enabled, False otherwise.
+        """
         return bool(self._get_config_setting("excessive_logging"))
 
 
     def describe(self) -> pd.DataFrame:
-        """Get a DataFrame describing the portal's current state"""
+        """Summarize the portal's current persistent and runtime state.
+
+        Returns:
+            pandas.DataFrame: A table with key characteristics, including
+            total crashes logged, today's crashes, and whether excessive
+            logging is enabled, combined with the base DataPortal summary.
+        """
         all_params = [super().describe()]
         all_params.append(_describe_persistent_characteristic(
             EXCEPTIONS_TOTAL_TXT, len(self._crash_history)))
@@ -603,7 +931,12 @@ class LoggingCodePortal(DataPortal):
 
 
     def _clear(self) -> None:
-        """Clear the portal's state"""
+        """Clear the portal's internal state and unregister handlers.
+
+        Side Effects:
+            - Drops references to crash/event/run histories.
+            - Unregisters global uncaught exception handlers.
+        """
         self._crash_history = None
         self._event_log = None
         self._run_history = None
@@ -611,10 +944,17 @@ class LoggingCodePortal(DataPortal):
         super()._clear()
 
 
-# register_parameterizable_class(LoggingCodePortal)
+def log_exception() -> None:
+    """Log the currently handled exception to the active LoggingCodePortal.
 
+    Captures the exception from sys.exc_info(), enriches it with execution
+    environment context, and stores it in the portal-level crash history. If
+    called during a function execution with excessive logging enabled, also
+    stores the event under the function's per-call crash log.
 
-def log_exception() -> None:
+    Returns:
+        None
+    """
     exc_type, exc_value, trace_back = sys.exc_info()
     if not _exception_needs_to_be_processed(
             exc_type, exc_value, trace_back):
@@ -642,6 +982,19 @@ def log_exception() -> None:
 
 
 def log_event(*args, **kwargs):
+    """Record an application event to the active LoggingCodePortal.
+
+    Adds environment context and optional positional messages to the event
+    payload. When called during a function execution, also attaches the event
+    to that call's event log.
+
+    Args:
+        *args: Optional positional messages to include in the event payload.
+        **kwargs: Key-value pairs forming the body of the event.
+
+    Returns:
+        None
+    """
     if len(LoggingFnExecutionFrame.call_stack):
         frame = LoggingFnExecutionFrame.call_stack[-1]
         event_id = frame.session_id + "_event_" + str(frame.event_counter)