pythagoras 0.24.6__py3-none-any.whl → 0.24.7__py3-none-any.whl

pythagoras/_080_pure_code_portals/pure_core_classes.py

@@ -51,6 +51,12 @@ CACHED_EXECUTION_RESULTS_TXT = "Cached execution results"
 EXECUTION_QUEUE_SIZE_TXT = "Execution queue size"
 
 class PureCodePortal(ProtectedCodePortal):
+    """Portal that manages execution and caching for pure functions.
+
+    The portal extends ProtectedCodePortal with two persistent dictionaries:
+    - execution_results: append-only, stores ValueAddr of function outputs
+    - execution_requests: mutable, tracks pending execution requests
+    """
 
     _execution_results: PersiDict | None
     _execution_requests: PersiDict | None
@@ -60,6 +66,14 @@ class PureCodePortal(ProtectedCodePortal):
             , p_consistency_checks: float | Joker = KEEP_CURRENT
             , excessive_logging: bool | Joker = KEEP_CURRENT
             ):
+        """Initialize a PureCodePortal instance.
+
+        Args:
+            root_dict: Backing persistent dictionary or path used to create it.
+            p_consistency_checks: Probability [0..1] to re-check cached
+                results for consistency. KEEP_CURRENT to inherit.
+            excessive_logging: Verbosity flag; KEEP_CURRENT to inherit.
+        """
         ProtectedCodePortal.__init__(self
             , root_dict=root_dict
             , p_consistency_checks=p_consistency_checks
@@ -89,7 +103,13 @@ class PureCodePortal(ProtectedCodePortal):
 
 
     def describe(self) -> pd.DataFrame:
-        """Get a DataFrame describing the portal's current state"""
+        """Describe the portal state as a DataFrame.
+
+        Returns:
+            pandas.DataFrame: Concatenated report that includes base portal
+            parameters plus counts of cached execution results and queued
+            execution requests.
+        """
         all_params = [super().describe()]
 
         all_params.append(_describe_persistent_characteristic(
@@ -102,6 +122,7 @@ class PureCodePortal(ProtectedCodePortal):
         return result
 
     def _clear(self):
+        """Release references to backing dicts and clear base portal state."""
         self._execution_results = None
         self._execution_requests = None
         super()._clear()
@@ -113,6 +134,12 @@ class PureFnCallSignature(ProtectedFnCallSignature):
     _execution_results_addr_cache: PureFnExecutionResultAddr | None
 
     def __init__(self, fn: PureFn, arguments: dict):
+        """Create a signature object for a specific PureFn call.
+
+        Args:
+            fn: The pure function being called.
+            arguments: Keyword arguments for the call.
+        """
         assert isinstance(fn, PureFn)
         assert isinstance(arguments, dict)
         super().__init__(fn, arguments)
@@ -132,6 +159,12 @@ class PureFnCallSignature(ProtectedFnCallSignature):
 
 
 class PureFn(ProtectedFn):
+    """Wrapper around a callable that provides pure-function semantics.
+
+    A PureFn executes inside a PureCodePortal, caches results by call
+    signature, and exposes convenience APIs to request execution, run
+    immediately, and retrieve results via address objects.
+    """
 
     def __init__(self, fn: Callable | str
                  , pre_validators: list[AutonomousFn] | List[Callable] | None = None
@@ -139,6 +172,17 @@ class PureFn(ProtectedFn):
                  , excessive_logging: bool | Joker = KEEP_CURRENT
                  , fixed_kwargs: dict | None = None
                  , portal: PureCodePortal | None = None):
+        """Construct a PureFn.
+
+        Args:
+            fn: Target callable.
+            pre_validators: Optional list of pre-execution validators.
+            post_validators: Optional list of post-execution validators.
+            excessive_logging: Verbosity flag; KEEP_CURRENT to inherit.
+            fixed_kwargs: Mapping of argument names to fixed values injected
+                into each call.
+            portal: Optional PureCodePortal to bind this PureFn to.
+        """
         ProtectedFn.__init__(self
                              , fn=fn
                              , portal = portal
@@ -149,21 +193,45 @@ class PureFn(ProtectedFn):
 
 
     def get_address(self, **kwargs) -> PureFnExecutionResultAddr:
-        """Get the address of the result of the function with the given arguments."""
+        """Build an address object for a call with the given arguments.
+
+        Args:
+            **kwargs: Keyword arguments to pass to the function.
+
+        Returns:
+            PureFnExecutionResultAddr: Address referencing the (cached or
+            future) result corresponding to the provided arguments.
+        """
         with self.portal:
             packed_kwargs = KwArgs(**kwargs).pack()
             return PureFnExecutionResultAddr(self, packed_kwargs)
 
 
     def get_signature(self, arguments: dict) -> PureFnCallSignature:
+        """Build a call signature for the given arguments.
+
+        Args:
+            arguments: Keyword arguments for a potential call.
+
+        Returns:
+            PureFnCallSignature: The signature object identifying the call.
+        """
         return PureFnCallSignature(self, arguments)
 
 
     def swarm(self, **kwargs) -> PureFnExecutionResultAddr:
-        """ Request execution of the function with the given arguments.
+        """Request background function execution for the given arguments.
+
+        The function is not executed immediately; instead, an execution request
+        is recorded in the portal. The returned address can later be used to
+        check readiness or retrieve the value.
 
-        The function is executed in the background. The result can be
-        retrieved later using the returned address.
+        Args:
+            **kwargs: Keyword arguments to pass to the underlying function.
+
+        Returns:
+            PureFnExecutionResultAddr: Address that identifies the pending (or
+            already cached) execution result for these arguments.
         """
         with self.portal:
             result_address = self.get_address(**kwargs)
@@ -171,10 +239,16 @@ class PureFn(ProtectedFn):
             return result_address
 
     def run(self, **kwargs) -> PureFnExecutionResultAddr:
-        """ Execute the function with the given arguments.
+        """Execute immediately and return the result address.
+
+        The function is executed synchronously within the current process.
+
+        Args:
+            **kwargs: Keyword arguments to pass to the underlying function.
 
-        The function is executed immediately. The result can be
-        retrieved later using the returned address.
+        Returns:
+            PureFnExecutionResultAddr: Address of the computed value (which can
+            be used to fetch logs/metadata or the value again if needed).
         """
         with self.portal:
             result_address = self.get_address(**kwargs)
@@ -183,12 +257,18 @@ class PureFn(ProtectedFn):
 
 
     def execute(self, **kwargs) -> Any:
-        """ Execute the function with the given arguments.
+        """Execute the function with the given arguments and return the result.
+
+        The function is executed immediately and its result is memoized by the
+        portal. Subsequent calls with identical arguments return the cached
+        value (optionally performing consistency checks depending on the
+        portal's p_consistency_checks setting).
+
+        Args:
+            **kwargs: Keyword arguments to pass to the underlying function.
 
-        The function is executed immediately, and the result is returned.
-        The result is memoized, so the function is actually executed
-        only the first time it's called; subsequent calls return the
-        cached result.
+        Returns:
+            Any: The computed result value.
         """
 
         with self.portal as portal:
@@ -224,6 +304,16 @@ class PureFn(ProtectedFn):
             self
             , list_of_kwargs:list[dict]
             ) -> list[PureFnExecutionResultAddr]:
+        """Queue background execution for a batch of argument sets.
+
+        Args:
+            list_of_kwargs: A list of keyword-argument mappings. Each mapping
+                represents one call to the function.
+
+        Returns:
+            list[PureFnExecutionResultAddr]: Addresses for all requested
+            executions, in the same order as the input list.
+        """
         assert isinstance(list_of_kwargs, (list, tuple))
         for kwargs in list_of_kwargs:
             assert isinstance(kwargs, dict)
@@ -244,6 +334,17 @@ class PureFn(ProtectedFn):
             self
             , list_of_kwargs:list[dict]
             ) -> list[PureFnExecutionResultAddr]:
+        """Execute a batch of calls immediately and return their addresses.
+
+        Execution is performed in a shuffled order.
+
+        Args:
+            list_of_kwargs: A list of keyword-argument mappings for each call.
+
+        Returns:
+            list[PureFnExecutionResultAddr]: Addresses for the executed calls,
+            in the same order as the input list.
+        """
         with self.portal:
             addrs = self.swarm_list(list_of_kwargs)
             addrs_workspace = copy(addrs)
@@ -275,6 +376,13 @@ class PureFn(ProtectedFn):
 
     @property
     def portal(self) -> PureCodePortal:
+        """Active PureCodePortal used for this function execution.
+
+        Returns:
+            PureCodePortal: The portal that governs execution and persistence
+            for this PureFn (falls back to the current active portal if this
+            function isn't explicitly bound).
+        """
         return super().portal
 
 
@@ -297,6 +405,12 @@ class PureFnExecutionResultAddr(HashAddr):
     _ready_cache: bool | None
 
     def __init__(self, fn: PureFn, arguments:dict[str, Any]):
+        """Create an address for a pure-function execution result.
+
+        Args:
+            fn: The PureFn whose execution result is addressed.
+            arguments: The keyword arguments for the call (packed dict).
+        """
         assert isinstance(fn, PureFn)
         with fn.portal as portal:
             self._kwargs_cache = KwArgs(**arguments)
@@ -339,6 +453,7 @@ class PureFnExecutionResultAddr(HashAddr):
 
     @property
     def call_signature(self) -> PureFnCallSignature:
+        """The PureFnCallSignature for this address' call."""
         if (not hasattr(self, "_call_signature_cache")
             or self._call_signature_cache is None):
             self._call_signature_cache = self.get_ValueAddr().get()
@@ -384,6 +499,15 @@ class PureFnExecutionResultAddr(HashAddr):
 
     @property
     def _ready_in_nonactive_portals(self) -> bool:
+        """Try importing a ready result from non-active portals.
+
+        If another known portal already has the execution result, copy the
+        corresponding key/value into the active portal's stores.
+
+        Returns:
+            bool: True if the value was found in a non-active portal and
+            imported; False otherwise.
+        """
         for another_portal in get_nonactive_portals():
             with another_portal:
                 if self in another_portal._execution_results:
@@ -399,6 +523,12 @@ class PureFnExecutionResultAddr(HashAddr):
 
     @property
     def ready(self) -> bool:
+        """Whether the execution result is already available.
+
+        Returns:
+            bool: True if the result is present in the active portal (or can
+            be imported from a known non-active portal); False otherwise.
+        """
         if hasattr(self, "_ready_cache"):
             assert self._ready_cache
             return True
@@ -413,7 +543,11 @@ class PureFnExecutionResultAddr(HashAddr):
 
 
     def execute(self):
-        """Execute the function and store the result in the portal."""
+        """Execute the function and store the result in the portal.
+
+        Returns:
+            Any: The computed result of the underlying pure function call.
+        """
         if hasattr(self, "_result_cache"):
             return self._result_cache
         with self.fn.portal:
@@ -439,7 +573,13 @@ class PureFnExecutionResultAddr(HashAddr):
 
     @property
     def execution_requested(self):
-        """Indicates if the function execution has been requested."""
+        """Whether execution for this call has been requested.
+
+        Returns:
+            bool: True if there's a pending execution request in the active
+            portal or any known non-active portal (also synchronizes the
+            request into the active portal); False otherwise.
+        """
         with self.fn.portal as active_portal:
             if self in active_portal._execution_requests:
                 return True
@@ -451,15 +591,22 @@ class PureFnExecutionResultAddr(HashAddr):
 
 
     def get(self, timeout: int = None):
-        """Retrieve value, referenced by the address.
+        """Retrieve the value referenced by this address, waiting if needed.
+
+        The method does not execute the function itself. If the value is not
+        immediately available, it requests execution and waits with
+        exponential backoff until the result arrives or the timeout elapses.
 
-        If the value is not immediately available, backoff exponentially
-        till timeout is exceeded. If timeout is None, keep trying forever.
+        Args:
+            timeout: Optional maximum number of seconds to wait. If None,
+                tries/waits indefinitely.
 
-        This method does not actually execute the function, but simply
-        retrieves the result of the function execution, if it is available.
-        If it is not available, the method waits for the result to become
-        available, or until the timeout is exceeded.
+        Returns:
+            Any: The value produced by the pure function call.
+
+        Raises:
+            TimeoutError: If the timeout elapses before the value becomes
+                available.
         """
         assert timeout is None or timeout >= 0
         if hasattr(self, "_result_cache"):
@@ -502,10 +649,16 @@ class PureFnExecutionResultAddr(HashAddr):
 
     @property
     def can_be_executed(self) -> PureFnCallSignature | ValidationSuccessFlag | None:
-        """Indicates if the function can be executed in the current session.
+        """Whether execution is currently feasible.
+
+        This checks pre-validators/guards for the underlying pure function and
+        returns a directive for the protected execution pipeline.
 
-        TODO: The function should be refactored once we start fully supporting
-        guards
+        Returns:
+            PureFnCallSignature | ValidationSuccessFlag | None: If a dependent
+            call must be executed first, returns its call signature; if checks
+            pass immediately, returns VALIDATION_SUCCESSFUL; otherwise None to
+            indicate that the execution is not possible.
         """
         with self.fn.portal:
             return self.fn.can_be_executed(self.kwargs)

pythagoras/_080_pure_code_portals/pure_decorator.py

@@ -29,6 +29,18 @@ from .._080_pure_code_portals.pure_core_classes import (
 from persidict import KEEP_CURRENT, Joker
 
 class pure(protected):
+    """Decorator that marks a function as pure and enables result caching.
+
+    Pure functions are assumed to be deterministic and free of side effects:
+    given the same arguments they always produce the same result. When you
+    decorate a function with @pure(), Pythagoras caches execution results in
+    a persistent store, avoids re-executing the function for identical calls,
+    as well as tracks source-code changes to recompute the function
+    when necessary.
+
+    This decorator is a thin, typed wrapper over the generic `protected`
+    decorator configured for pure-function semantics.
+    """
 
     def __init__(self
                  , pre_validators: list[ValidatorFn] | None = None
@@ -37,6 +49,22 @@ class pure(protected):
                  , excessive_logging: bool | Joker = KEEP_CURRENT
                  , portal: PureCodePortal | None = None
                  ):
+        """Initialize the pure decorator.
+
+        Args:
+            pre_validators: Optional list of validator functions that run
+                before execution.
+            post_validators: Optional list of validator functions that run
+                after execution to validate results or side conditions.
+            fixed_kwargs: Mapping of argument names to values that will be
+                always injected into the decorated function calls.
+            excessive_logging: Controls verbosity inside the portal; keep
+                KEEP_CURRENT to inherit from the active portal, True/False to
+                override.
+            portal: Optional PureCodePortal to bind the decorated function to.
+                If omitted, the portal(s) to use will be inferred
+                during the function call(s).
+        """
         protected.__init__(self=self
                            , portal=portal
                            , excessive_logging=excessive_logging
@@ -46,6 +74,15 @@ class pure(protected):
 
 
     def __call__(self, fn:Callable|str) -> PureFn:
+        """Wrap a function as a PureFn within a PureCodePortal.
+
+        Args:
+            fn: The target callable or its import path string.
+
+        Returns:
+            PureFn: A wrapped function instance that supports memoized
+            execution via run/swarm/execute and address-based retrieval.
+        """
         wrapper = PureFn(fn
                          , portal=self._portal
                          , pre_validators=self._pre_validators

pythagoras/_080_pure_code_portals/recursion_pre_validator.py

@@ -1,3 +1,10 @@
+"""Pre-validators that help with recursive pure functions.
+
+This module provides utilities to short-circuit or schedule execution for
+recursive calls, e.g., Fibonacci-like functions. The pre-validator returns
+either a success flag (skip execution), a call signature to be executed first,
+or None to proceed as usual.
+"""
 from unittest import result
 
 import pythagoras as pth
@@ -14,6 +21,26 @@ def _recursion_pre_validator(
         , fn_addr:ValueAddr
         , param_name:str
         )-> PureFnCallSignature | ValidationSuccessFlag | None:
+    """Pre-validator to aid recursion by ensuring prerequisites are ready.
+
+    For a non-negative integer parameter specified by param_name, this
+    validator checks whether smaller sub-problems have already been computed.
+    It returns:
+    - VALIDATION_SUCCESSFUL if a base case is detected or all smaller results
+      are already available; or
+    - a PureFnCallSignature for the smallest missing sub-problem to compute
+      first; or
+    - None to proceed normally.
+
+    Args:
+        packed_kwargs: Packed arguments (KwArgs) of the current call.
+        fn_addr: ValueAddr pointing to the underlying PureFn.
+        param_name: Name of the recursive integer argument to inspect.
+
+    Returns:
+        PureFnCallSignature | ValidationSuccessFlag | None: Directive for the
+        protected execution pipeline.
+    """
     unpacked_kwargs = packed_kwargs.unpack()
     assert param_name in unpacked_kwargs
     fn = fn_addr.get()
@@ -49,6 +76,18 @@ def _recursion_pre_validator(
 def recursive_parameters(
         *args
         ) -> list[ComplexPreValidatorFn]:
+    """Build pre-validators for one or more recursive parameters.
+
+    Each provided name produces a pre-validator function that uses
+    _recursion_pre_validator to ensure prerequisite sub-problems are ready.
+
+    Args:
+        *args: One or more names of integer parameters that govern recursion.
+
+    Returns:
+        list[ComplexPreValidatorFn]: A list of pre-validators to plug into the
+        pure/protected decorator configuration.
+    """
     result = []
     for name in args:
         assert isinstance(name, str)

pythagoras/_090_swarming_portals/output_suppressor.py

@@ -1,13 +1,32 @@
+"""Utilities for silencing worker process output.
+
+This module provides a small context manager that redirects stdout and stderr
+to the system null device (os.devnull). It is used by swarming workers to keep
+background processing quiet and avoid polluting logs or test output.
+"""
+
 import os
 from contextlib import ExitStack, redirect_stderr, redirect_stdout
 
 
-
 class OutputSuppressor:
-    """A context manager that suppresses stdout and stderr output."""
+    """Context manager to suppress stdout and stderr.
+
+    Example:
+        with OutputSuppressor():
+            noisy_function()
+
+    Notes:
+        Internally uses contextlib.ExitStack to manage all redirections and to
+        ensure restoration even when exceptions are raised.
+    """
 
     def __enter__(self):
-        """Redirect stdout and stderr to os.devnull."""
+        """Enter the suppression context.
+
+        Returns:
+            OutputSuppressor: The context manager instance.
+        """
         self._stack = ExitStack()
         devnull = self._stack.enter_context(open(os.devnull, "w"))
         self._stack.enter_context(redirect_stdout(devnull))
@@ -15,4 +34,14 @@ class OutputSuppressor:
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the suppression context, restoring stdio streams.
+
+        Args:
+            exc_type: Exception class if an exception occurred, else None.
+            exc_val: Exception instance if an exception occurred, else None.
+            exc_tb: Traceback if an exception occurred, else None.
+
+        Returns:
+            bool: Whatever is returned by ExitStack.__exit__().
+        """
         return self._stack.__exit__(exc_type, exc_val, exc_tb)