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

pythagoras/_030_data_portals/data_portal_core_classes.py

@@ -14,10 +14,7 @@ from .._800_signatures_and_converters import get_hash_signature
 from .._010_basic_portals.basic_portal_core_classes import (
     _describe_persistent_characteristic
     , _describe_runtime_characteristic)
-from .._020_ordinary_code_portals import (
-    get_normalized_function_source
-    ,OrdinaryCodePortal
-    ,OrdinaryFn)
+from .._020_ordinary_code_portals import OrdinaryCodePortal ,OrdinaryFn
 from persidict import WriteOnceDict
 
 TOTAL_VALUES_TXT = "Values, total"
@@ -25,36 +22,63 @@ PROBABILITY_OF_CHECKS_TXT = "Probability of consistency checks"
 
 
 def get_active_data_portal() -> DataPortal:
+    """Return the currently active DataPortal.
+
+    Returns:
+        DataPortal: The portal that is active in the current context ("with" block).
+
+    Raises:
+        AssertionError: If the active portal is not an instance of DataPortal.
+    """
     portal = get_active_portal()
     assert isinstance(portal, DataPortal)
     return portal
 
 
 def get_nonactive_data_portals() -> list[DataPortal]:
-    """Get a list of all nonactive DataPortals"""
+    """Return all known DataPortals that are not currently active.
+
+    Returns:
+        list[DataPortal]: A list of DataPortal instances that are available to
+            the runtime but are not the current active portal stack.
+
+    Raises:
+        AssertionError: If any returned portal is not an instance of DataPortal.
+    """
     portals = get_nonactive_portals()
     assert all(isinstance(p, DataPortal) for p in portals)
     return portals
 
 
 class DataPortal(OrdinaryCodePortal):
-    """A portal that persistently stores values.
-
-    Immutable values are accessible via their hash_address-es,
-    which are unique identifiers of the values.
+    """A portal that persistently stores and retrieves immutable values.
+
+    A DataPortal is responsible for addressing, storing, and retrieving
+    values by their content-derived addresses. It exposes a context manager
+    interface so that code running within a "with portal:" block treats that
+    portal as the active one.
+
+    Behavior overview:
+    - Content-addressed storage: immutable values are referenced by a
+      HashAddr/ValueAddr that is derived from the value's bytes and a
+      human-readable descriptor.
+    - Transparent fetch and replication: if a value is not present in the
+      active portal but exists in any other known portal, it is fetched
+      and copied into the active portal on demand.
+    - Config settings: portal-specific and function-specific settings are
+      persisted in a dedicated config store.
+    - Consistency checks: the underlying persistent dictionary can perform
+      random, probabilistic consistency checks controlled by the
+      p_consistency_checks parameter.
+
+    Note:
+        Use the portal as a context manager whenever code performs I/O with
+        the portal (reading or storing values):
 
-    If the current portal does not contain a specific value,
-    referenced by a hash_address, but this value can be retrieved
-    from another portal known to the program,
-    the value will be automatically copied to the current portal.
-
-    A portal can serve as a context manager, enabling the use of the
-    'with' statement to support portal-aware code blocks. If some code is
-    supposed to explicitly read anything from (or save to) a portal,
-    it should be wrapped in a 'with' statement that
-    marks the portal as active for the duration of the code block.
+        with portal:
+            addr = ValueAddr(data)
+            value = addr.get()
 
-    DataPortal also supports random consistency checks.
     """
 
     _value_store: WriteOnceDict | None
@@ -67,6 +91,18 @@ class DataPortal(OrdinaryCodePortal):
             , root_dict: PersiDict|str|None = None
             , p_consistency_checks: float|Joker = KEEP_CURRENT
             ):
+        """Initialize a DataPortal.
+
+        Args:
+            root_dict: Prototype PersiDict or a path/URI used to create
+                a persistent dictionary for internal stores. If None, uses
+                the parent's default.
+            p_consistency_checks: Probability in [0, 1] or KEEP_CURRENT Joker
+                that controls random consistency checks of the value store.
+
+        Raises:
+            ValueError: If p_consistency_checks is not in [0, 1] and not a Joker.
+        """
         OrdinaryCodePortal.__init__(self, root_dict = root_dict)
         del root_dict
         self._auxiliary_config_params_at_init = dict()
@@ -102,14 +138,24 @@ class DataPortal(OrdinaryCodePortal):
 
 
     def _post_init_hook(self) -> None:
-        """Hook to be called after all __init__ methods are done"""
+        """Finalize initialization after __init__ completes across the MRO.
+
+        Ensures that auxiliary configuration parameters are persisted and that
+        the value store is configured according to the portal's
+        p_consistency_checks setting.
+        """
         super()._post_init_hook()
         self._persist_initial_config_params()
         self._value_store.p_consistency_checks = self.p_consistency_checks
 
 
     def get_params(self) -> dict:
-        """Get the portal's configuration parameters"""
+        """Return the portal's configuration parameters.
+
+        Returns:
+            dict: A sorted dictionary of base parameters augmented with
+            auxiliary config entries defined at initialization.
+        """
         params = super().get_params()
         params.update(self._auxiliary_config_params_at_init)
         sorted_params = sort_dict_by_keys(params)
@@ -201,6 +247,12 @@ class StorableFn(OrdinaryFn):
         , fn: Callable | str
         , portal: DataPortal | None = None
         ):
+        """Create a storable wrapper around an ordinary function.
+
+        Args:
+            fn: A Python function or its source code (normalized) as a string.
+            portal: Optional DataPortal to bind the function to.
+        """
         OrdinaryFn.__init__(self, fn=fn, portal=portal)
         self._auxiliary_config_params_at_init = dict()
 

pythagoras/_030_data_portals/ready_and_get.py

@@ -5,11 +5,32 @@ from .data_portal_core_classes import HashAddr
 
 
 def ready(obj) -> bool:
-    """Return True if all objects in the data structure are ready."""
+    """Check readiness of a possibly nested data structure.
+
+    Recursively inspects the structure and returns True only if every
+    HashAddr/ValueAddr contained is ready. Strings and bytes-like objects are
+    treated as atomic. Lists, tuples, and dicts are traversed recursively.
+
+    Args:
+        obj: Any Python object, possibly a nested combination of lists, tuples,
+            and dicts containing HashAddr/ValueAddr objects.
+
+    Returns:
+        bool: True if all contained addresses are ready; False otherwise.
+    """
     return _ready_impl(obj)
 
 def _ready_impl(obj, seen=None):
-    """Return True if all objects in the data structure are ready."""
+    """Implementation helper for ready() with cycle protection.
+
+    Args:
+        obj: Object under inspection.
+        seen: A set of object ids already visited to prevent infinite loops
+            on cyclic graphs.
+
+    Returns:
+        bool: True if obj and all nested addresses are ready.
+    """
     if seen is None:
         seen = set()
     elif id(obj) in seen:
@@ -36,12 +57,32 @@ def _ready_impl(obj, seen=None):
 
 
 def get(obj:Any) -> Any:
-    """Return copy of data structure with addresses replaced with objects."""
+    """Deep-copy a structure, replacing HashAddr/ValueAddr with values.
+
+    Traverses the structure and replaces every address with the value
+    obtained via .get(), preserving container topology. Handles cycles by
+    memoizing objects during traversal.
+
+    Args:
+        obj: Any Python object or nested structure containing addresses.
+
+    Returns:
+        Any: A copy of obj with all addresses resolved into concrete values.
+    """
     return _get_impl(obj)
 
 
 def _get_impl(obj:Any, seen=None)->Any:
-    """Return copy of data structure with addresses replaced with objects."""
+    """Implementation helper for get() with cycle protection and memoization.
+
+    Args:
+        obj: Object to resolve.
+        seen: A dict mapping visited object ids to their resolved copies,
+            used to preserve identities and break cycles.
+
+    Returns:
+        Any: The resolved object or a structure containing resolved values.
+    """
     if seen is None:
         seen = dict()
 

pythagoras/_030_data_portals/storable_decorator.py

@@ -4,15 +4,32 @@ from .._020_ordinary_code_portals import ordinary
 from .data_portal_core_classes import DataPortal, StorableFn
 
 class storable(ordinary):
-    """A decorator that converts a Python function into a StorableFn object.
+    """Decorator that converts a Python function into a StorableFn.
+
+    When applied, the function is wrapped into a StorableFn that can be
+    addressed and stored in a DataPortal.
     """
 
     def __init__(self
             , portal: DataPortal | None = None):
+        """Create a storable decorator bound to an optional DataPortal.
+
+        Args:
+            portal: The DataPortal to use as default when wrapping functions.
+                If None, the active portal at call time will be used.
+        """
         assert isinstance(portal, DataPortal) or portal is None
         ordinary.__init__(self=self, portal=portal)
 
     def __call__(self,fn:Callable)->StorableFn:
+        """Wrap the given function into a StorableFn.
+
+        Args:
+            fn: The ordinary Python function to wrap.
+
+        Returns:
+            StorableFn: A storable function bound to the configured portal.
+        """
         wrapper = StorableFn(fn
             , portal=self._portal)
         return wrapper

pythagoras/_040_logging_code_portals/exception_processing_tracking.py

@@ -1,5 +1,20 @@
 def _exception_needs_to_be_processed(exc_type, exc_value, trace_back) -> bool:
-    """Chack if the exception needs to be logged by Pythagoras"""
+    """Determine whether an exception should be logged by Pythagoras.
+
+    Args:
+        exc_type: The exception class (type of the raised exception). May be None.
+        exc_value: The exception instance.
+        trace_back: The traceback object associated with the exception.
+
+    Returns:
+        bool: True if the exception has not yet been marked as processed by
+        Pythagoras and should be logged; False otherwise.
+
+    Notes:
+        Pythagoras marks exceptions it already handled to avoid duplicate
+        logging. This function checks for such marks using either
+        Exception.add_note (Python 3.11+) or a fallback attribute.
+    """
     if exc_type is None:
         return False
 
@@ -16,7 +31,20 @@ def _exception_needs_to_be_processed(exc_type, exc_value, trace_back) -> bool:
 
 
 def _mark_exception_as_processed(exc_type, exc_value, trace_back) -> None:
-    """Mark the exception as processed by Pythagoras"""
+    """Mark an exception as already processed by Pythagoras.
+
+    This mark prevents duplicate logging of the same exception by subsequent
+    handlers.
+
+    Args:
+        exc_type: The exception class (type of the raised exception). Unused.
+        exc_value: The exception instance to mark.
+        trace_back: The traceback object associated with the exception. Unused.
+
+    Side Effects:
+        - Mutates the exception by adding a note (preferred) or by setting
+          an attribute `__suppress_pythagoras_logging__ = True`.
+    """
     if hasattr(exc_value, "add_note"):
         exc_value.add_note(
             "__suppress_pythagoras_logging__")

pythagoras/_040_logging_code_portals/execution_environment_summary.py

@@ -9,46 +9,82 @@ from .notebook_checker import is_executed_in_notebook
 from .._010_basic_portals import BasicPortal
 
 
-def build_execution_environment_summary()-> Dict:
-    """Capture core information about execution environment.
+def build_execution_environment_summary() -> Dict:
+    """Build a snapshot of the current execution environment.
 
-    The function is intended to be used to log environment information
-    to help debug (distributed) applications.
+    Gathers system, process, and Python runtime metadata useful for diagnosing
+    issues, particularly in distributed or long-running applications.
+
+    Returns:
+        Dict: A dictionary containing environment details such as hostname,
+        user, process ID, OS/platform, Python version, CPU/memory stats,
+        working directory, local timezone, and whether execution is inside a
+        Jupyter notebook.
     """
     cwd = os.getcwd()
 
     execution_environment_summary = dict(
-        hostname = socket.gethostname()
-        ,user = getuser()
-        ,pid = os.getpid()
-        ,platform = platform.platform()
-        ,python_implementation = platform.python_implementation()
-        ,python_version = platform.python_version()
-        ,processor = platform.processor()
-        ,cpu_count = psutil.cpu_count()
-        ,cpu_load_avg = psutil.getloadavg()
-        # ,cuda_gpu_count=torch.cuda.device_count()
-        ,disk_usage = psutil.disk_usage(cwd)
-        ,virtual_memory = psutil.virtual_memory()
-        ,working_directory = cwd
-        ,local_timezone = datetime.now().astimezone().tzname()
-        ,is_in_notebook = is_executed_in_notebook()
-        )
+        hostname=socket.gethostname(),
+        user=getuser(),
+        pid=os.getpid(),
+        platform=platform.platform(),
+        python_implementation=platform.python_implementation(),
+        python_version=platform.python_version(),
+        processor=platform.processor(),
+        cpu_count=psutil.cpu_count(),
+        cpu_load_avg=psutil.getloadavg(),
+        # cuda_gpu_count=torch.cuda.device_count(),
+        disk_usage=psutil.disk_usage(cwd),
+        virtual_memory=psutil.virtual_memory(),
+        working_directory=cwd,
+        local_timezone=datetime.now().astimezone().tzname(),
+        is_in_notebook=is_executed_in_notebook(),
+    )
 
     return execution_environment_summary
 
-def make_unique_name(suggested_name:str, existing_names) -> str:
-    """Make a name unique by adding a random suffix to it."""
+def make_unique_name(suggested_name: str, existing_names) -> str:
+    """Return a unique name based on the suggestion and a set of existing names.
+
+    If the suggested name already exists, appends a random numeric
+    suffix until a unique candidate is found.
+
+    Args:
+        suggested_name: Preferred base name.
+        existing_names: A collection supporting membership check (e.g., dict,
+            set, list) used to determine collisions.
+
+    Returns:
+        str: A name guaranteed to not be present in existing_names at the
+        time of checking.
+    """
     candidate = suggested_name
     entropy_infuser = BasicPortal._entropy_infuser
     while candidate in existing_names:
         candidate = suggested_name + "_"
-        random_number = entropy_infuser.randint(1,10_000_000_000)
+        random_number = entropy_infuser.randint(1, 10_000_000_000)
         candidate += str(random_number)
     return candidate
 
 def add_execution_environment_summary(*args, **kwargs):
-    """Add execution environment summary to kwargs. """
+    """Augment keyword arguments with an execution environment summary.
+
+    Optionally also adds positional messages under a unique `message_list` key
+    when args are provided. This is primarily used to enrich logged events with
+    contextual runtime information.
+
+    Args:
+        *args: Optional messages or payloads to attach under `message_list`.
+        **kwargs: The keyword arguments dictionary to be augmented. Mutated in
+            place by adding a unique key for the environment summary.
+
+    Returns:
+        dict: The same kwargs dict, with additional keys:
+            - execution_environment_summary*: A unique key containing the env
+              summary built by build_execution_environment_summary().
+            - message_list*: A unique key containing the provided args (if any).
+              Asterisks denote keys may be suffixed to ensure uniqueness.
+    """
     context_param_name = "execution_environment_summary"
     context_param_name = make_unique_name(
         suggested_name=context_param_name, existing_names=kwargs)

pythagoras/_040_logging_code_portals/kw_args.py

@@ -6,24 +6,37 @@ from .._030_data_portals import DataPortal, ValueAddr
 from parameterizable import sort_dict_by_keys
 
 class KwArgs(dict):
-    """ A class that encapsulates keyword arguments for a function call.
+    """Container for keyword arguments with deterministic ordering and packing.
 
-    It allows "normalizing" the dictionary by sorting the keys
-    and replacing values with their hash addresses
-    in order to always get the same hash values
-    for the same lists of arguments.
+    Provides utilities to sort keys deterministically and to pack/unpack values
+    to and from ValueAddr instances so that argument sets can be compared and
+    hashed reliably across runs.
     """
 
 
     def __init__(self, *args, **kargs):
+        """Create a KwArgs mapping with deterministically sorted keys.
+
+        Args:
+            *args: Positional arguments accepted by dict().
+            **kargs: Keyword arguments accepted by dict().
+        """
         dict.__init__(self)
         tmp_dict = dict(*args, **kargs)
         tmp_dict = sort_dict_by_keys(tmp_dict)
         self.update(tmp_dict)
 
 
-    def sort(self, inplace:bool) -> KwArgs:
-        """Sort the keys in the dictionary."""
+    def sort(self, inplace: bool) -> KwArgs:
+        """Return a version with keys sorted, optionally in place.
+
+        Args:
+            inplace: If True, sorts this instance and returns it. If False,
+                returns a new KwArgs instance with sorted keys.
+
+        Returns:
+            KwArgs: The sorted KwArgs (self when inplace=True, otherwise a new instance).
+        """
         if inplace:
             sorted_dict = sort_dict_by_keys(self)
             self.clear()
@@ -34,7 +47,18 @@ class KwArgs(dict):
 
 
     def __setitem__(self, key, value):
-        """Overridden to ensure only string keys are allowed."""
+        """Set an item enforcing KwArgs invariants.
+
+        Enforces that keys are strings and values are not KwArgs themselves.
+
+        Args:
+            key: The key to set; must be a str.
+            value: The value to associate with the key.
+
+        Raises:
+            KeyError: If the key is not a string.
+            ValueError: If the value is a KwArgs (nested KwArgs are disallowed).
+        """
         if not isinstance(key, str):
             raise KeyError("Keys must be strings in KwArgs.")
         if isinstance(value, KwArgs):
@@ -43,15 +67,24 @@ class KwArgs(dict):
 
 
     def __reduce__(self):
-        """ Sort the keys before pickling."""
+        """Support pickling by sorting keys first for stable serialization.
+
+        Returns:
+            tuple: Standard pickle reduce tuple from dict.__reduce__().
+        """
         self.sort(inplace=True)
         return super().__reduce__()
 
 
     def unpack(self) -> UnpackedKwArgs:
-        """ Restore values based on their hash addresses."""
+        """Return a copy with all ValueAddr values resolved to raw values.
+
+        Returns:
+            UnpackedKwArgs: A new mapping where each ValueAddr is replaced with
+            its underlying value via ValueAddr.get().
+        """
         unpacked_copy = dict()
-        for k,v in self.items():
+        for k, v in self.items():
             if isinstance(v, ValueAddr):
                 unpacked_copy[k] = v.get()
             else:
@@ -61,7 +94,20 @@ class KwArgs(dict):
 
 
     def pack(self, store = True) -> PackedKwArgs:
-        """ Replace values with their hash addresses."""
+        """Pack values into ValueAddr handles, optionally storing them.
+
+        Each argument value is replaced by a ValueAddr pointing to either the
+        stored value (when store=True) or a non-stored address (when store=False)
+        that can still serve as a stable identifier for hashing/equality.
+
+        Args:
+            store: If True, values are stored in the active portal and the
+                returned addresses persist across sessions. If False, produces
+                non-stored addresses suitable for transient signatures.
+
+        Returns:
+            PackedKwArgs: A new mapping with values converted to ValueAddr.
+        """
         packed_copy = dict()
         if store:
             portal = get_active_portal()
@@ -77,10 +123,26 @@ class KwArgs(dict):
 
 
 class PackedKwArgs(KwArgs):
+    """KwArgs where all values are ValueAddr instances.
+
+    This is the packed form produced by KwArgs.pack().
+    """
     def __init__(self,*args, **kargs):
+        """Construct a PackedKwArgs mapping.
+
+        Accepts the same arguments as dict/KwArgs.
+        """
         super().__init__(*args, **kargs)
 
 
 class UnpackedKwArgs(KwArgs):
+    """KwArgs where all values are raw (non-ValueAddr) objects.
+
+    This is the unpacked form produced by KwArgs.unpack().
+    """
     def __init__(self,*args, **kargs):
+        """Construct an UnpackedKwArgs mapping.
+
+        Accepts the same arguments as dict/KwArgs.
+        """
         super().__init__(*args, **kargs)

pythagoras/_040_logging_code_portals/logging_decorator.py

@@ -6,19 +6,41 @@ from .._030_data_portals import storable
 from .logging_portal_core_classes import LoggingCodePortal, LoggingFn
 
 class logging(storable):
-    """A decorator that converts a Python function into a LoggingFn object.
+    """Decorator that converts a Python function into a LoggingFn.
+
+    When applied, the target function is wrapped into a LoggingFn that records
+    execution attempts, results, outputs, crashes, and events via a
+    LoggingCodePortal.
     """
     _excessive_logging: bool|Joker
 
     def __init__(self
             , excessive_logging:bool|Joker = KEEP_CURRENT
             , portal: LoggingCodePortal | None = None):
+        """Initialize the logging decorator.
+
+        Args:
+            excessive_logging: If True, the wrapped function will capture
+                detailed per-execution artifacts (attempt context, outputs,
+                and results). If KEEP_CURRENT, inherits from the wrapped
+                LoggingFn or the active portal.
+            portal: Optional LoggingCodePortal to bind the wrapped function to.
+                If None, the active portal at execution time is used.
+        """
         assert isinstance(excessive_logging, (bool,Joker))
         assert isinstance(portal, LoggingCodePortal) or portal is None
         storable.__init__(self=self, portal=portal)
         self._excessive_logging = excessive_logging
 
     def __call__(self,fn:Callable)->LoggingFn:
+        """Wrap the function into a LoggingFn.
+
+        Args:
+            fn: A plain Python callable to decorate.
+
+        Returns:
+            LoggingFn: The logging-enabled wrapper for the given function.
+        """
         wrapper = LoggingFn(fn
             , excessive_logging=self._excessive_logging
             , portal=self._portal)