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

pythagoras/_060_autonomous_code_portals/names_usage_analyzer.py

@@ -4,7 +4,23 @@ from typing import Callable, Union
 from .._020_ordinary_code_portals import get_normalized_function_source
 
 class NamesUsedInFunction:
+    """Container for name usage sets discovered in a function.
+
+    Attributes:
+        function: Name of the top-level function being analyzed.
+        explicitly_global_unbound_deep: Names explicitly marked as global in the
+            function or its nested functions, which are not locally bound.
+        explicitly_nonlocal_unbound_deep: Names explicitly marked as nonlocal in
+            the function or its nested functions, which are not locally bound.
+        local: Names bound locally in the top-level function (including args).
+        imported: Names explicitly imported within the function body.
+        unclassified_deep: Names used in the function and/or nested functions
+            that are neither imported nor explicitly marked global/nonlocal.
+        accessible: All names currently considered accessible within function
+            scope during analysis; a union built as nodes are visited.
+    """
     def __init__(self):
+        """Initialize all name sets to empty defaults."""
         self.function = None # name of the function
         self.explicitly_global_unbound_deep = set() # names, explicitly marked as global inside the function and/or called subfunctions, yet not bound to any object
         self.explicitly_nonlocal_unbound_deep = set() # names, explicitly marked as nonlocal inside the function and/or called subfunctions, yet not bound to any object
@@ -21,12 +37,23 @@ class NamesUsageAnalyzer(ast.NodeVisitor):
     """
     # TODO: add support for structural pattern matching
     def __init__(self):
+        """Initialize the analyzer state and counters."""
         self.names = NamesUsedInFunction()
         self.imported_packages_deep = set()
         self.func_nesting_level = 0
         self.n_yelds = 0
 
     def visit_FunctionDef(self, node):
+        """Handle a function definition.
+
+        - For the top-level function: record its name, parameters as locals,
+          and traverse its body.
+        - For nested functions: analyze them with a fresh analyzer and merge
+          relevant sets into the current analyzer, adjusting for accessibility.
+
+        Args:
+            node: The ast.FunctionDef node.
+        """
         if self.func_nesting_level == 0:
             self.names.function = node.name
             self.func_nesting_level += 1
@@ -54,6 +81,15 @@ class NamesUsageAnalyzer(ast.NodeVisitor):
             # self.n_yelds is not changing
 
     def visit_Name(self, node):
+        """Track variable usage and binding for a Name node.
+
+        - On load: if the name is not accessible, mark it unclassified and
+          accessible.
+        - On store: register it as a local and accessible.
+
+        Args:
+            node: The ast.Name node.
+        """
         if isinstance(node.ctx, ast.Load):
             if node.id not in self.names.accessible:
                 self.names.unclassified_deep |= {node.id}
@@ -65,23 +101,58 @@ class NamesUsageAnalyzer(ast.NodeVisitor):
         self.generic_visit(node)
 
     def visit_Attribute(self, node):
+        """Visit an attribute access expression.
+
+        Currently no special handling is required; traversal continues.
+
+        Args:
+            node: The ast.Attribute node.
+        """
         self.generic_visit(node)
 
     def visit_Yield(self, node):
+        """Record usage of a yield expression.
+
+        Increments the number of yields found, which disqualifies autonomy.
+
+        Args:
+            node: The ast.Yield node.
+        """
         self.n_yelds += 1
         self.generic_visit(node)
 
     def visit_YieldFrom(self, node):
+        """Record usage of a 'yield from' expression.
+
+        Increments the number of yields found, which disqualifies autonomy.
+
+        Args:
+            node: The ast.YieldFrom node.
+        """
         self.n_yelds += 1
         self.generic_visit(node)
 
     def visit_Try(self, node):
+        """Track names bound in exception handlers within try/except.
+
+        Exception handler names become local and accessible.
+
+        Args:
+            node: The ast.Try node.
+        """
         for handler in node.handlers:
             self.names.local |= {handler.name}
             self.names.accessible |= {handler.name}
         self.generic_visit(node)
 
     def visit_comprehension(self, node):
+        """Handle variable binding within a comprehension clause.
+
+        Targets in comprehension generators become local and accessible.
+
+        Args:
+            node: The ast.comprehension node or a loop node with a similar API.
+        """
         if isinstance(node.target, (ast.Tuple, ast.List)):
             all_targets =node.target.elts
         else:
@@ -94,29 +165,59 @@ class NamesUsageAnalyzer(ast.NodeVisitor):
         self.generic_visit(node)
 
     def visit_For(self, node):
+        """Handle a for-loop comprehension-like binding.
+
+        Args:
+            node: The ast.For node.
+        """
         self.visit_comprehension(node)
 
     def visit_ListComp(self, node):
+        """Handle bindings within a list comprehension.
+
+        Args:
+            node: The ast.ListComp node.
+        """
         for gen in node.generators:
             self.visit_comprehension(gen)
         self.generic_visit(node)
 
     def visit_SetComp(self, node):
+        """Handle bindings within a set comprehension.
+
+        Args:
+            node: The ast.SetComp node.
+        """
         for gen in node.generators:
             self.visit_comprehension(gen)
         self.generic_visit(node)
 
     def visit_DictComp(self, node):
+        """Handle bindings within a dict comprehension.
+
+        Args:
+            node: The ast.DictComp node.
+        """
         for gen in node.generators:
             self.visit_comprehension(gen)
         self.generic_visit(node)
 
     def visit_GeneratorExp(self, node):
+        """Handle bindings within a generator expression.
+
+        Args:
+            node: The ast.GeneratorExp node.
+        """
         for gen in node.generators:
             self.visit_comprehension(gen)
         self.generic_visit(node)
 
     def visit_Import(self, node):
+        """Register imported names and top-level package usage.
+
+        Args:
+            node: The ast.Import node.
+        """
         for alias in node.names:
             name = alias.asname if alias.asname else alias.name
             self.names.imported |= {name}
@@ -125,6 +226,11 @@ class NamesUsageAnalyzer(ast.NodeVisitor):
         self.generic_visit(node)
 
     def visit_ImportFrom(self, node):
+        """Register names imported from a module and the module itself.
+
+        Args:
+            node: The ast.ImportFrom node.
+        """
         self.imported_packages_deep |= {node.module.split('.')[-1]}
         for alias in node.names:
             name = alias.asname if alias.asname else alias.name
@@ -133,12 +239,22 @@ class NamesUsageAnalyzer(ast.NodeVisitor):
         self.generic_visit(node)
 
     def visit_Nonlocal(self, node):
+        """Record names declared as nonlocal within the function.
+
+        Args:
+            node: The ast.Nonlocal node.
+        """
         nonlocals =  set(node.names)
         self.names.explicitly_nonlocal_unbound_deep |= nonlocals
         self.names.accessible |= nonlocals
         self.generic_visit(node)
 
     def visit_Global(self, node):
+        """Record names declared as global within the function.
+
+        Args:
+            node: The ast.Global node.
+        """
         globals = set(node.names)
         self.names.explicitly_global_unbound_deep |= globals
         self.names.accessible |= globals
@@ -147,11 +263,24 @@ class NamesUsageAnalyzer(ast.NodeVisitor):
 def analyze_names_in_function(
         a_func: Union[Callable,str]
         ):
-    """Analyze names used in a function.
+    """Analyze names used in a single conventional function.
+
+    The function source is normalized, decorators are skipped, and an AST is
+    parsed. Assertions ensure that exactly one top-level regular function
+    definition is present. The tree is visited with NamesUsageAnalyzer.
+
+    Args:
+        a_func: A function object or its source string to analyze.
+
+    Returns:
+        dict: A mapping with keys:
+            - tree (ast.Module): The parsed AST module with a single function.
+            - analyzer (NamesUsageAnalyzer): The populated analyzer instance.
+            - normalized_source (str): The normalized source code.
 
-    It returns an instance of NamesUsageAnalyzer class,
-    which contains all the data needed to analyze
-    names, used by the function.
+    Raises:
+        AssertionError: If the input is not a single regular function (e.g., a
+            lambda, async function, callable class, or multiple definitions).
     """
 
     normalized_source = get_normalized_function_source(a_func)

pythagoras/_070_protected_code_portals/list_flattener.py

@@ -1,12 +1,50 @@
+from typing import List, Any
 
 
-def flatten_list(nested_list):
-    """Flatten a list with unlimited nesting levels."""
-    assert isinstance(nested_list, list)
+def flatten_list(nested_list: List[Any]) -> List[Any]:
+    """Flatten a nested list into a single-level list.
+
+    This function flattens lists of arbitrary depth using an iterative
+    (non-recursive) algorithm. Only values of type ``list`` are treated as
+    containers to be expanded. Other iterable types (e.g., tuples, sets,
+    strings, generators) are considered atomic values and are not traversed.
+
+    Parameters:
+    - nested_list: list
+        A possibly nested Python list. Must be an instance of ``list``.
+
+    Returns:
+    - list
+        A new list containing all elements from ``nested_list`` in their
+        original left-to-right order, but with one level of nesting (flat).
+
+    Raises:
+    - TypeError: If ``nested_list`` is not a ``list`` instance.
+
+    Notes:
+    - Preserves the order of elements.
+    - Supports unlimited nesting depth without recursion.
+    - Cyclic references (e.g., a list that contains itself, directly or
+      indirectly) will lead to an infinite loop.
+
+    Examples:
+    >>> flatten_list([1, [2, 3, [4]], 5])
+    [1, 2, 3, 4, 5]
+    >>> flatten_list([["a", ["b"]], "c"]) 
+    ['a', 'b', 'c']
+    >>> flatten_list([(1, 2), [3, 4]])
+    [(1, 2), 3, 4]
+    """
+    if not isinstance(nested_list, list):
+        raise TypeError(f"Expected list, got {type(nested_list).__name__}")
     flattened = []
-    for item in nested_list:
-        if isinstance(item, list):
-            flattened.extend(flatten_list(item))
+    stack = [nested_list]
+
+    while stack:
+        current = stack.pop()
+        if isinstance(current, list):
+            stack.extend(reversed(current))
         else:
-            flattened.append(item)
+            flattened.append(current)
+
     return flattened

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)