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

pythagoras/_070_protected_code_portals/protected_portal_core_classes.py

@@ -30,18 +30,54 @@ from .._060_autonomous_code_portals import *
 
 
 class ProtectedCodePortal(AutonomousCodePortal):
+    """Portal for protected code execution.
+
+    This portal specializes the AutonomousCodePortal to coordinate execution of
+    ProtectedFn instances. It carries configuration and storage
+    required by validators (e.g., retry throttling) and by protected function
+    orchestration.
+
+    Args:
+        root_dict (PersiDict | str | None): Optional persistent dictionary or a
+            path/identifier to initialize the portal's storage. If None, a
+            default in-memory storage may be used.
+        p_consistency_checks (float | Joker): Probability or flag controlling
+            internal consistency checks performed by the portal. Use
+            KEEP_CURRENT to inherit the current setting.
+        excessive_logging (bool | Joker): Enables verbose logging of portal and
+            function operations. Use KEEP_CURRENT to inherit the current
+            setting.
+    """
     
     def __init__(self
             , root_dict: PersiDict|str|None = None
             , p_consistency_checks: float|Joker = KEEP_CURRENT
             , excessive_logging: bool|Joker = KEEP_CURRENT
             ):
+        """Initialize the portal.
+
+        Args:
+            root_dict (PersiDict | str | None): Backing storage or its path.
+                If None, use default.
+            p_consistency_checks (float | Joker): Probability for internal
+                consistency checks (or KEEP_CURRENT to inherit).
+            excessive_logging (bool | Joker): Verbose logging flag
+                (KEEP_CURRENT to inherit).
+        """
         super().__init__(root_dict=root_dict
             , p_consistency_checks=p_consistency_checks
             , excessive_logging=excessive_logging)
 
 
 class ProtectedFn(AutonomousFn):
+    """Function wrapper that enforces pre/post validation around execution.
+
+    A ProtectedFn evaluates a sequence of pre-validators before executing the
+    underlying function and a sequence of post-validators after execution. If a
+    pre-validator returns a ProtectedFnCallSignature, that signature will be
+    executed first (allowing validators to perform prerequisite actions) before
+    re-attempting the validation/execution loop.
+    """
 
     _pre_validators_cache: list[ValidatorFn] | None
     _post_validators_cache: list[ValidatorFn] | None
@@ -57,6 +93,25 @@ class ProtectedFn(AutonomousFn):
                  , excessive_logging: bool | Joker = KEEP_CURRENT
                  , fixed_kwargs: dict[str,Any] | None = None
                  , portal: ProtectedCodePortal | None = None):
+        """Construct a ProtectedFn.
+
+        Args:
+            fn (Callable | str): The underlying Python function or its source
+                code string.
+            pre_validators (list[ValidatorFn] | list[Callable] | ValidatorFn | Callable | None):
+                Pre-execution validators. Callables are wrapped into
+                PreValidatorFn. Lists can be nested and will
+                be flattened.
+            post_validators (list[ValidatorFn] | list[Callable] | ValidatorFn | Callable | None):
+                Post-execution validators. Callables are wrapped into
+                PostValidatorFn. Lists can be nested and will be flattened.
+            excessive_logging (bool | Joker): Enable verbose logging or inherit
+                current setting with KEEP_CURRENT.
+            fixed_kwargs (dict[str, Any] | None): Keyword arguments to be fixed
+                (bound) for every execution of the function.
+            portal (ProtectedCodePortal | None): Portal instance to bind the
+                function to.
+        """
         super().__init__(fn=fn
             , portal = portal
             , fixed_kwargs=fixed_kwargs
@@ -114,6 +169,11 @@ class ProtectedFn(AutonomousFn):
 
     @property
     def pre_validators(self) -> list[AutonomousFn]:
+        """List of pre-validator functions for this protected function.
+
+        Returns:
+            list[AutonomousFn]: A cached list of PreValidatorFn instances.
+        """
         if not hasattr(self, "_pre_validators_cache"):
             self._pre_validators_cache = [
                 addr.get() for addr in self._pre_validators_addrs]
@@ -122,6 +182,11 @@ class ProtectedFn(AutonomousFn):
 
     @property
     def post_validators(self) -> list[AutonomousFn]:
+        """List of post-validator functions for this protected function.
+
+        Returns:
+            list[AutonomousFn]: A cached list of PostValidatorFn instances.
+        """
         if not hasattr(self, "_post_validators_cache"):
             self._post_validators_cache = [
                 addr.get() for addr in self._post_validators_addrs]
@@ -131,6 +196,21 @@ class ProtectedFn(AutonomousFn):
     def can_be_executed(self
             , kw_args: KwArgs
             ) -> ProtectedFnCallSignature|ValidationSuccessFlag|None:
+        """Run pre-validators to determine if execution can proceed.
+
+        The portal will shuffle the order of pre-validators. If any validator
+        returns a ProtectedFnCallSignature, that signature should be executed by
+        the caller prior to executing the protected function (this method simply
+        returns it). If any validator fails, None is returned. If all succeed,
+        VALIDATION_SUCCESSFUL is returned.
+
+        Args:
+            kw_args (KwArgs): Arguments intended for the wrapped function.
+
+        Returns:
+            ProtectedFnCallSignature | ValidationSuccessFlag | None: Either a
+            signature to execute first, the success flag, or None on failure.
+        """
         with self.portal as portal:
             kw_args = kw_args.pack()
             pre_validators = copy(self.pre_validators)
@@ -150,6 +230,16 @@ class ProtectedFn(AutonomousFn):
     def validate_execution_result(self
             , kw_args: KwArgs
             , result: Any) -> ValidationSuccessFlag|None:
+        """Run post-validators to confirm the execution result is acceptable.
+
+        Args:
+            kw_args (KwArgs): Arguments that were passed to the protected function.
+            result (Any): The value returned by the protected function.
+
+        Returns:
+            ValidationSuccessFlag | None: VALIDATION_SUCCESSFUL if all
+                post-validators pass, otherwise None.
+        """
         with self.portal as portal:
             kw_args = kw_args.pack()
             post_validators = copy(self.post_validators)
@@ -162,6 +252,24 @@ class ProtectedFn(AutonomousFn):
 
 
     def execute(self, **kwargs) -> Any:
+        """Execute the protected function with validation.
+
+        This method performs the following loop:
+        - Runs pre-validators. If a pre-validator returns a
+          ProtectedFnCallSignature, that signature is executed and validation is
+          reattempted. If any pre-validator fails, an AssertionError is raised.
+        - Executes the wrapped function.
+        - Runs post-validators and asserts they all succeed.
+
+        Args:
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Returns:
+            Any: The result returned by the wrapped function.
+
+        Raises:
+            AssertionError: If pre- or post-validation fails.
+        """
         with (self.portal):
             kw_args = KwArgs(**kwargs)
             while True:
@@ -182,8 +290,21 @@ class ProtectedFn(AutonomousFn):
             ) -> list[ValidatorFn]:
         """Return list of validators in a normalized form.
 
-        All the functions-validators are converted to AutonomousFn objects,
-        and returned as a list, sorted by functions' hash signatures.
+        - Wraps plain callables/strings into appropriate ValidatorFn subclasses.
+        - Flattens nested lists.
+        - Removes duplicates while inforcing deterministic
+          order via sort_dict_by_keys.
+
+        Args:
+            validators (list[ValidatorFn] | ValidatorFn | None): Validators in
+                any supported representation (single, list, nested lists, etc.).
+            validator_type (type): Either PreValidatorFn or PostValidatorFn.
+
+        Returns:
+            list[ValidatorFn]: A sorted list of validator instances.
+
+        Raises:
+            TypeError: If an unexpected validator_type is provided.
         """
         assert validator_type in {PreValidatorFn, PostValidatorFn}
         if validators is None:
@@ -216,6 +337,12 @@ class ProtectedFn(AutonomousFn):
 
     @property
     def portal(self) -> ProtectedCodePortal:
+        """Return the bound ProtectedCodePortal.
+
+        Returns:
+            ProtectedCodePortal: The portal controlling execution context and
+            storage for this protected function.
+        """
         return super().portal
 
 
@@ -240,14 +367,33 @@ class ProtectedFn(AutonomousFn):
 
 
     def get_signature(self, arguments:dict) -> ProtectedFnCallSignature:
+        """Create a call signature for this protected function.
+
+        Args:
+            arguments (dict): Arguments to bind into the call signature.
+
+        Returns:
+            ProtectedFnCallSignature: Signature object representing a
+            particular call to this function.
+        """
         return ProtectedFnCallSignature(self, arguments)
 
 
 class ProtectedFnCallSignature(AutonomousFnCallSignature):
-    """A signature of a call to a pure function"""
+    """Invocation signature for a protected function.
+
+    Encapsulates a function reference and bound arguments that can be executed
+    later via execute().
+    """
     _fn_cache: ProtectedFn | None
 
     def __init__(self, fn: ProtectedFn, arguments: dict):
+        """Initialize the signature.
+
+        Args:
+            fn (ProtectedFn): The protected function to call.
+            arguments (dict): Keyword arguments to be passed at execution time.
+        """
         assert isinstance(fn, ProtectedFn)
         assert isinstance(arguments, dict)
         super().__init__(fn, arguments)
@@ -259,10 +405,26 @@ class ProtectedFnCallSignature(AutonomousFnCallSignature):
 
 
 class ValidatorFn(AutonomousFn):
+    """Base class for validator wrappers.
+
+    A ValidatorFn ensures the wrapped callable accepts exactly the keyword
+    arguments declared by get_allowed_kwargs_names(). Subclasses define the
+    specific interface for pre/post validation phases.
+    """
     def __init__(self, fn: Callable | str | AutonomousFn
         , fixed_kwargs: dict | None = None
         , excessive_logging: bool | Joker = KEEP_CURRENT
         , portal: AutonomousCodePortal | None = None):
+        """Initialize a validator function wrapper.
+
+        Args:
+            fn (Callable | str | AutonomousFn): The validator implementation or
+                its source code.
+            fixed_kwargs (dict | None): Keyword arguments fixed for every
+                validation call.
+            excessive_logging (bool | Joker): Controls verbose logging.
+            portal (AutonomousCodePortal | None): Optional portal binding.
+        """
         super().__init__(
             fn=fn
             , fixed_kwargs=fixed_kwargs
@@ -274,20 +436,52 @@ class ValidatorFn(AutonomousFn):
 
     @classmethod
     def get_allowed_kwargs_names(cls)->set[str]:
+        """Return the exact set of allowed keyword argument names.
+
+        Subclasses must override to declare their interface.
+
+        Returns:
+            set[str]: Names of keyword arguments accepted by execute().
+        """
         raise NotImplementedError("This method must be overridden")
 
 
     def execute(self,**kwargs) \
             -> ProtectedFnCallSignature | ValidationSuccessFlag | None:
+        """Execute the validator after verifying keyword arguments.
+
+        Args:
+            **kwargs: Must exactly match get_allowed_kwargs_names().
+
+        Returns:
+            ProtectedFnCallSignature | ValidationSuccessFlag | None: Depending
+            on the validator type and outcome.
+        """
         assert set(kwargs) == self.get_allowed_kwargs_names()
         return super().execute(**kwargs)
 
 
 class PreValidatorFn(ValidatorFn):
+    """Base class for pre-execution validators.
+
+    Pre-validators are executed before the protected function. They may return:
+    - VALIDATION_SUCCESSFUL to indicate execution can proceed;
+    - ProtectedFnCallSignature to request execution of an auxiliary action
+      prior to re-validating;
+    - None to indicate failure.
+    """
     def __init__(self, fn: Callable | str | AutonomousFn
         , fixed_kwargs: dict | None = None
         , excessive_logging: bool | Joker = KEEP_CURRENT
         , portal: AutonomousCodePortal | None = None):
+        """Initialize a pre-execution validator wrapper.
+
+        Args:
+            fn (Callable | str | AutonomousFn): The pre-validator implementation.
+            fixed_kwargs (dict | None): Keyword arguments fixed for every call.
+            excessive_logging (bool | Joker): Controls verbose logging.
+            portal (AutonomousCodePortal | None): Optional portal binding.
+        """
         super().__init__(
             fn=fn
             , fixed_kwargs=fixed_kwargs
@@ -296,10 +490,22 @@ class PreValidatorFn(ValidatorFn):
 
 
 class SimplePreValidatorFn(PreValidatorFn):
+    """A pre-validator that takes no runtime inputs.
+
+    The wrapped callable must accept no parameters; use fixed_kwargs only.
+    """
     def __init__(self, fn: Callable | str | AutonomousFn
         , fixed_kwargs: dict | None = None
         , excessive_logging: bool | Joker = KEEP_CURRENT
         , portal: AutonomousCodePortal | None = None):
+        """Initialize a simple pre-validator.
+
+        Args:
+            fn (Callable | str | AutonomousFn): The implementation.
+            fixed_kwargs (dict | None): Fixed keyword arguments, if any.
+            excessive_logging (bool | Joker): Controls verbose logging.
+            portal (AutonomousCodePortal | None): Optional portal binding.
+        """
         super().__init__(
             fn=fn
             , fixed_kwargs=fixed_kwargs
@@ -314,10 +520,23 @@ class SimplePreValidatorFn(PreValidatorFn):
 
 
 class ComplexPreValidatorFn(PreValidatorFn):
+    """A pre-validator that can inspect inputs and the function address.
+
+    The callable must accept the keyword arguments named
+    packed_kwargs and fn_addr.
+    """
     def __init__(self, fn: Callable | str | AutonomousFn
         , fixed_kwargs: dict | None = None
         , excessive_logging: bool | Joker = KEEP_CURRENT
         , portal: AutonomousCodePortal | None = None):
+        """Initialize a complex pre-validator.
+
+        Args:
+            fn (Callable | str | AutonomousFn): The implementation.
+            fixed_kwargs (dict | None): Fixed keyword arguments, if any.
+            excessive_logging (bool | Joker): Controls verbose logging.
+            portal (AutonomousCodePortal | None): Optional portal binding.
+        """
         super().__init__(
             fn=fn
             , fixed_kwargs=fixed_kwargs
@@ -332,10 +551,22 @@ class ComplexPreValidatorFn(PreValidatorFn):
 
 
 class PostValidatorFn(ValidatorFn):
+    """Post-execution validator wrapper.
+
+    The callable must accept packed_kwargs, fn_addr, and result.
+    """
     def __init__(self, fn: Callable | str | AutonomousFn
         , fixed_kwargs: dict | None = None
         , excessive_logging: bool | Joker = KEEP_CURRENT
         , portal: AutonomousCodePortal | None = None):
+        """Initialize a post-execution validator.
+
+        Args:
+            fn (Callable | str | AutonomousFn): The implementation.
+            fixed_kwargs (dict | None): Fixed keyword arguments, if any.
+            excessive_logging (bool | Joker): Controls verbose logging.
+            portal (AutonomousCodePortal | None): Optional portal binding.
+        """
         super().__init__(
             fn=fn
             , fixed_kwargs=fixed_kwargs
@@ -344,5 +575,9 @@ class PostValidatorFn(ValidatorFn):
 
     @classmethod
     def get_allowed_kwargs_names(cls) -> set[str]:
-        """Post-validators use info about the function, its input arguments and returned value."""
+        """Post-validators use function metadata, inputs, and the result.
+
+        Returns:
+            set[str]: {"packed_kwargs", "fn_addr", "result"}
+        """
         return {"packed_kwargs", "fn_addr", "result" }

pythagoras/_070_protected_code_portals/system_utils.py

@@ -3,13 +3,41 @@ import psutil
 import pynvml
 
 def get_unused_ram_mb() -> int:
-    """Returns the amount of available RAM in MB. """
+    """Get the currently available RAM on the system in megabytes (MB).
+
+    Returns:
+        int: Integer number of megabytes of RAM that are currently available
+        to user processes as reported by psutil.virtual_memory().available.
+
+    Notes:
+        - The value is rounded down to the nearest integer.
+        - Uses powers-of-two conversion (1 MB = 1024^2 bytes).
+        - On systems with memory compression or overcommit, this value is an
+          approximation provided by the OS.
+    """
     free_ram = psutil.virtual_memory().available / (1024 * 1024)
     return int(free_ram)
 
 
 def get_unused_cpu_cores() -> float:
-    """Returns the free (logical) CPU capacity"""
+    """Estimate currently unused logical CPU capacity in units of CPU cores.
+
+    On POSIX systems with load average support, this uses the 1-minute load
+    average to estimate remaining capacity: max(logical_cores - load1, 0).
+    On other systems, it falls back to instantaneous CPU percent usage as
+    reported by psutil and computes: logical_cores * (1 - usage/100).
+
+    Returns:
+        float: A non-negative float representing approximate available logical
+        CPU cores. For example, 2.5 means roughly two and a half cores free.
+
+    Notes:
+        - The number of logical cores (with SMT/Hyper-Threading) is used.
+        - If psutil reports near-zero usage, a small default (0.5%) is assumed
+          to avoid transient 0.0 readings.
+        - This is a heuristic; short spikes and scheduling nuances may cause
+          deviations from actual availability.
+    """
 
     cnt = psutil.cpu_count(logical=True) or 1
 
@@ -24,7 +52,20 @@ def get_unused_cpu_cores() -> float:
 
 
 def process_is_active(pid: int) -> bool:
-    """Checks if a process with the given PID is active."""
+    """Check whether a process with the given PID is currently active.
+
+    Args:
+        pid (int): Operating system process identifier (PID).
+
+    Returns:
+        bool: True if the process exists and is running; False if it does not
+        exist, has exited, or cannot be inspected due to permissions or other
+        errors.
+
+    Notes:
+        - Any exception from psutil (e.g., NoSuchProcess, AccessDenied) results
+          in a False return value for safety.
+    """
     try:
         process = psutil.Process(pid)
         return process.is_running()
@@ -33,7 +74,19 @@ def process_is_active(pid: int) -> bool:
 
 
 def get_process_start_time(pid: int) -> int:
-    """Returns the start time of the process with the given PID."""
+    """Get the UNIX timestamp of when a process started.
+
+    Args:
+        pid (int): Operating system process identifier (PID).
+
+    Returns:
+        int: Start time as a UNIX timestamp (seconds since epoch). Returns 0 if
+        the process does not exist or cannot be accessed.
+
+    Notes:
+        - Any exception from psutil (e.g., NoSuchProcess, AccessDenied) results
+          in a 0 return value for safety.
+    """
     try:
         process = psutil.Process(pid)
         return int(process.create_time())
@@ -42,21 +95,41 @@ def get_process_start_time(pid: int) -> int:
 
 
 def get_current_process_id() -> int:
-    """Returns the current process ID."""
+    """Get the current process ID (PID).
+
+    Returns:
+        int: The PID of the running Python process.
+    """
     return psutil.Process().pid
 
 
 def get_current_process_start_time() -> int:
-    """Returns the start time of the current process."""
+    """Get the UNIX timestamp for when the current Python process started.
+
+    Returns:
+        int: Start time as a UNIX timestamp (seconds since epoch). Returns 0 on
+        unexpected error.
+    """
     return get_process_start_time(get_current_process_id())
 
 
 def get_unused_nvidia_gpus() -> float:
-    """Returns the total unused GPU capacity as a float value.
-
-    The function calculates the sum of unused capacity across all available NVIDIA GPUs.
-    For example, 2.0 means two completely unused GPUs
-    0 is returned if no GPUs or on error.
+    """Estimate the total unused NVIDIA GPU capacity across all devices.
+
+    This aggregates the per-GPU unused utilization percentage (100 - gpu%) and
+    returns the sum in "GPU units". For example, 2.0 means capacity equivalent
+    to two fully idle GPUs. If no NVIDIA GPUs are present or NVML is unavailable,
+    the function returns 0.0.
+
+    Returns:
+        float: Sum of unused GPU capacity across all NVIDIA GPUs in GPU units.
+
+    Notes:
+        - Requires NVIDIA Management Library (pynvml) to be installed and the
+          NVIDIA driver to be available.
+        - Utilization is based on instantaneous NVML readings and may fluctuate.
+        - Any NVML error (e.g., no devices, driver issues) results in 0.0 for
+          safety.
     """
     try:
         pynvml.nvmlInit()
@@ -70,7 +143,7 @@ def get_unused_nvidia_gpus() -> float:
 
         return unused_capacity / 100.0
 
-    except pynvml.NVMLError as e:
+    except pynvml.NVMLError:
         # Return 0.0 on any NVML error (no GPUs, driver issues, etc.)
         return 0.0
     finally:

pythagoras/_070_protected_code_portals/validation_succesful_const.py

@@ -1,11 +1,16 @@
-class ValidationSuccessFlag:
-    """Singleton class to represent a successful validation."""
+from persidict.singletons import Singleton
 
-    _instance = None
 
-    def __new__(cls):
-        if cls._instance is None:
-            cls._instance = super().__new__(cls)
-        return cls._instance
+class ValidationSuccessFlag(Singleton):
+    """Marker singleton indicating that validation has succeeded.
 
+    This lightweight class is used as a unique sentinel object that signals a
+    successful validation outcome in protected code portals. Using a singleton
+    avoids ambiguity with other truthy values.
+    """
+    pass
+
+
+# A canonical, importable singleton value representing a successful validation.
+# Use identity checks (``is VALIDATION_SUCCESSFUL``) rather than equality.
 VALIDATION_SUCCESSFUL = ValidationSuccessFlag()