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

pythagoras/_070_protected_code_portals/package_manager.py

@@ -1,23 +1,55 @@
+"""Utilities to install and uninstall Python packages at runtime.
+
+This module provides a thin wrapper around pip and the uv tool to install
+and uninstall packages from within the running Python process.
+
+Key points:
+- By default, uv is preferred as the installer frontend (uv pip ...). If uv
+  or pip is not available, the module will attempt to install the missing
+  tool as needed.
+- For safety, uninstall_package refuses to operate on 'pip' or 'uv' directly.
+- Calls are synchronous and raise on non-zero exit status.
+"""
+
 import subprocess
 import importlib
 import sys
+from functools import lru_cache
 from typing import Optional
 
-_uv_and_pip_installation_needed:bool = True
 
-def _install_uv_and_pip() -> None:
-    global _uv_and_pip_installation_needed
-    if not _uv_and_pip_installation_needed:
-        return
+def _run(command: list[str]) -> str:
+    """Run command; raise RuntimeError on failure."""
+    try:
+        subprocess.run(command, check=True, stdout=subprocess.PIPE
+            , stderr=subprocess.STDOUT, text=True)
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(
+            f"Command failed: {' '.join(command)}\n{e.stdout}") from e
+
 
+@lru_cache(maxsize=1) # ensure only one call to _install_uv_and_pip
+def _install_uv_and_pip() -> None:
+    """Ensure the 'uv' and 'pip' frontends are available.
+
+    Behavior:
+    - If this helper has already run in the current process and determined
+      the tools are present, it returns immediately.
+    - Tries to import 'uv'; if missing, installs it using system pip
+      (use_uv=False).
+    - Tries to import 'pip'; if missing, installs it using uv (use_uv=True).
+
+    This function is an internal helper and is called implicitly by
+    install_package() for any package other than 'pip' or 'uv'.
+    """
     try:
         importlib.import_module("uv")
-    except:
+    except ModuleNotFoundError:
         install_package("uv", use_uv=False)
 
     try:
         importlib.import_module("pip")
-    except:
+    except ModuleNotFoundError:
         install_package("pip", use_uv=True)
 
 
@@ -26,13 +58,40 @@ def install_package(package_name:str
         , version:Optional[str]=None
         , use_uv:bool = True
         ) -> None:
-    """Install package using pip."""
-
-    if package_name == "pip":
-        assert use_uv
-    elif package_name == "uv":
-        assert not use_uv
-    else:
+    """Install a Python package using uv (default) or pip.
+
+    Parameters:
+    - package_name: Name of the package to install. Special cases:
+      - 'pip': must be installed using uv (use_uv=True).
+      - 'uv' : must be installed using pip (use_uv=False).
+    - upgrade: If True, pass "--upgrade" to the installer.
+    - version: Optional version pin, e.g. "1.2.3". If provided, constructs
+      "package_name==version".
+    - use_uv: If True, run as `python -m uv pip install ...`; otherwise use pip.
+
+    Behavior:
+    - Ensures both uv and pip are available unless installing one of them.
+    - Runs the installer in a subprocess with check=True (raises on failure).
+    - Imports the package after installation to verify it is importable.
+
+    Raises:
+    - RuntimeError: if the installation command fails.
+    - ValueError: if package_name or version are invalid, or if attempting
+      to install pip with use_uv=False or uv with use_uv=True.
+    - ModuleNotFoundError: if the package cannot be imported after installation.
+    """
+
+    if not package_name or not isinstance(package_name, str):
+        raise ValueError("package_name must be a non-empty string")
+
+    if version and not isinstance(version, str):
+        raise ValueError("version must be a string")
+
+    if package_name == "pip" and not use_uv:
+            raise ValueError("pip must be installed using uv (use_uv=True)")
+    elif package_name == "uv" and use_uv:
+            raise ValueError("uv must be installed using pip (use_uv=False)")
+    elif package_name not in ("pip", "uv"):
         _install_uv_and_pip()
 
     if use_uv:
@@ -46,30 +105,46 @@ def install_package(package_name:str
     package_spec = f"{package_name}=={version}" if version else package_name
     command += [package_spec]
 
-    subprocess.run(command, check=True, stdout=subprocess.PIPE
-        , stderr=subprocess.STDOUT, text=True)
+    _run(command)
 
+    # Verify import. Note: assumes package name matches importable module name.
     importlib.import_module(package_name)
 
 
 def uninstall_package(package_name:str, use_uv:bool=True)->None:
-    """Uninstall package using uv or pip."""
+    """Uninstall a Python package using uv (default) or pip.
+
+    Parameters:
+    - package_name: Name of the package to uninstall. Must not be 'pip' or 'uv'.
+    - use_uv: If True, run `python -m uv pip uninstall <name>`; otherwise use pip with "-y".
+
+    Behavior:
+    - Runs the uninstaller in a subprocess with check=True.
+    - Attempts to import and reload the package after uninstallation. If that
+      succeeds, raises an Exception to indicate the package still appears installed.
 
-    assert package_name not in ["pip", "uv"]
+    Raises:
+    - ValueError: if package_name is 'pip' or 'uv'.
+    - RuntimeError: if the uninstall command fails, or if post-uninstall
+      validation indicates the package is still importable.
+    """
+
+    if package_name in ["pip", "uv"]:
+        raise ValueError(f"Cannot uninstall '{package_name}' "
+                         "- it's a protected package")
 
     if use_uv:
         command = [sys.executable, "-m", "uv", "pip", "uninstall", package_name]
     else:
         command = [sys.executable, "-m", "pip", "uninstall", "-y", package_name]
 
-    subprocess.run(command, check=True, stdout=subprocess.PIPE
-        , stderr=subprocess.STDOUT, text=True)
+    _run(command)
 
     try:
         package = importlib.import_module(package_name)
         importlib.reload(package)
-    except:
+        raise RuntimeError(
+            f"Package '{package_name}' still importable after uninstallation")
+    except ModuleNotFoundError:
         pass
-    else:
-        raise Exception(
-            f"Failed to validate package uninstallation for '{package_name}'. ")
+

pythagoras/_070_protected_code_portals/protected_portal_core_classes.py

@@ -30,6 +30,24 @@ 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
@@ -42,6 +60,14 @@ class ProtectedCodePortal(AutonomousCodePortal):
 
 
 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 +83,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 +159,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 +172,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 +186,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)

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()

pythagoras/_800_signatures_and_converters/base_16_32_convertors.py

@@ -1,48 +1,83 @@
+from typing import Final
 
-base32_alphabet = '0123456789abcdefghijklmnopqrstuv'
-base32_alphabet_map = {char:index for index,char in enumerate(base32_alphabet)}
+_BASE32_ALPHABET: Final[str] = '0123456789abcdefghijklmnopqrstuv'
+_BASE32_ALPHABET_MAP: Final[dict[str, int]] = {
+    char:index for index,char in enumerate(_BASE32_ALPHABET)}
 
 
 def convert_base16_to_base32(hexdigest: str) -> str:
-    """
-    Convert a hexadecimal (base 16) string to a base 32 string.
+    """Convert a hexadecimal (base16) string to this project's base32.
+
+    Args:
+        hexdigest (str): A hexadecimal string (case-insensitive). May be an
+            empty string or "0" to represent zero.
 
-    :name hexdigest: A string representing a hexadecimal number.
-    :return: A string representing the equivalent number in base 32.
+    Returns:
+        str: The corresponding value encoded with the custom base32 alphabet
+        (digits 0-9 then letters a-v).
+
+    Examples:
+        >>> convert_base16_to_base32("ff")
+        '7v'
     """
 
-    if not hexdigest:
-        return '0'
-    num = int(hexdigest,16)
+    try:
+        num = int(hexdigest, 16)
+    except ValueError as e:
+        raise ValueError(f"Invalid hexadecimal string: {hexdigest}") from e
+
     base32_str = convert_int_to_base32(num)
 
     return base32_str
 
 
 def convert_int_to_base32(n: int) -> str:
-    """
-    Convert an integer to a base 32 string.
+    """Convert a non-negative integer to Pythagoras' base32 string.
+
+    Args:
+        n (int): Non-negative integer to encode.
+
+    Returns:
+        str: The base32 representation.
 
-    :name n: An integer.
-    :return: A string representing the equivalent number in base 32.
+    Raises:
+        ValueError: If n is negative.
     """
+    if n < 0:
+        raise ValueError("n must be non-negative")
+
+    if n == 0:
+        return "0"
+
     base32_str = ''
     while n > 0:
-        base32_str = base32_alphabet[n & 31] + base32_str
+        base32_str = _BASE32_ALPHABET[n & 31] + base32_str
         n >>= 5
 
     return base32_str
 
 def convert_base_32_to_int(digest: str) -> int:
-    """
-    Convert a base 32 string to an integer.
+    """Convert a base32 string (custom alphabet) to an integer.
 
-    :name digest: A string representing a number in base 32.
-    :return: An integer representing the equivalent number.
+    Args:
+        digest (str): String encoded with Pythagoras' base32 alphabet.
+
+    Returns:
+        int: The decoded non-negative integer value.
+
+    Raises:
+        KeyError: If digest contains a character outside the supported
+            base32 alphabet (0-9, a-v).
     """
+    if not digest:
+        raise ValueError("Digest cannot be empty")
+
     digest = digest.lower()
     num = 0
-    for char in digest:
-        num = num * 32 + base32_alphabet_map[char]
+    try:
+        for char in digest:
+            num = num * 32 + _BASE32_ALPHABET_MAP[char]
+    except KeyError as e:
+        raise ValueError(f"Invalid character '{e.args[0]}' in base32 digest: {digest}") from e
     return num
 

pythagoras/_800_signatures_and_converters/current_date_gmt_str.py

@@ -1,11 +1,26 @@
 from datetime import datetime, timezone
+from typing import Final
 
+_MONTH_ABBREVIATIONS: Final[tuple[str, ...]] = (
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
 
-def current_date_gmt_string():
-    """ Return the current date and time in the format '2024_12Jan_22_utc'
+
+def current_date_gmt_string() -> str:
+    """Get the current UTC date as a compact string.
+
+    Produces an underscore-delimited UTC date string suitable for
+    stable file names and log records.
+
+    The format is: "YYYY_MMMonAbbrev_dd_utc" (e.g., "2024_12Dec_11_utc").
+
+    Returns:
+        str: The formatted UTC date string, for the current moment.
     """
 
     utc_now = datetime.now(timezone.utc)
-    date_str = utc_now.strftime("%Y_%m%b_%d_utc")
-
-    return date_str
+    month_abbrev = _MONTH_ABBREVIATIONS[utc_now.month - 1]
+    # locale-dependent month abbreviation
+    result =  (f"{utc_now.year}_{utc_now.month:02d}{month_abbrev}" +
+              f"_{utc_now.day:02d}_utc")
+    return result

pythagoras/_800_signatures_and_converters/hash_signatures.py

@@ -1,33 +1,69 @@
 import sys
-from typing import Any
+from typing import Any, Final
 
 import joblib.hashing
 
 from .base_16_32_convertors import convert_base16_to_base32
 
 
-hash_type: str = "sha256"
-max_signature_length: int = 22
+_HASH_TYPE: Final[str] = "sha256"
+_MAX_SIGNATURE_LENGTH: Final[int] = 22
 
 def get_base16_hash_signature(x:Any) -> str:
-    """Return base16 hash signature of an object.
+    """Compute a hexadecimal (base16) hash for an arbitrary Python object.
 
-    Uses joblib's Hasher (or NumpyHasher). It uses Pickle for serialization,
-    except for NumPy arrays, which use optimized custom routines.
+    This function delegates to joblib's hashing utilities. If NumPy is
+    imported in the current process, it uses NumpyHasher for efficient and
+    stable hashing of NumPy arrays; otherwise it uses the generic Hasher.
+
+    Args:
+        x (Any): The object to hash. Must be picklable by joblib unless a
+            specialized routine (e.g., for NumPy arrays) is available.
+
+    Returns:
+        str: A hexadecimal string digest computed with the configured
+            algorithm (sha256 by default).
+
+    Notes:
+        - joblib relies on pickle for most Python objects; ensure that custom
+          objects are picklable for stable results.
+        - The digest is deterministic for the same object content.
     """
     if 'numpy' in sys.modules:
-        hasher = joblib.hashing.NumpyHasher(hash_name=hash_type)
+        hasher = joblib.hashing.NumpyHasher(hash_name=_HASH_TYPE)
     else:
-        hasher = joblib.hashing.Hasher(hash_name=hash_type)
+        hasher = joblib.hashing.Hasher(hash_name=_HASH_TYPE)
     hash_signature = hasher.hash(x)
     return str(hash_signature)
 
 def get_base32_hash_signature(x:Any) -> str:
-    """Return base32 hash signature of an object"""
+    """Compute a base32-encoded hash for an arbitrary Python object.
+
+    Internally computes a hexadecimal digest first, then converts it to the
+    custom base32 alphabet used by Pythagoras.
+
+    Args:
+        x (Any): The object to hash.
+
+    Returns:
+        str: The full-length base32 digest string (not truncated).
+    """
     base_16_hash = get_base16_hash_signature(x)
     base_32_hash = convert_base16_to_base32(base_16_hash)
     return base_32_hash
 
 def get_hash_signature(x:Any) -> str:
-    return get_base32_hash_signature(x)[:max_signature_length]
+    """Compute a short, URL-safe hash signature for an object.
+
+    This is a convenience wrapper that returns the first max_signature_length
+    characters of the base32 digest, which is typically sufficient for
+    collision-resistant identifiers in logs and filenames.
+
+    Args:
+        x (Any): The object to hash.
+
+    Returns:
+        str: The truncated base32 digest string.
+    """
+    return get_base32_hash_signature(x)[:_MAX_SIGNATURE_LENGTH]