pythagoras 0.24.4__tar.gz → 0.24.6__tar.gz

{pythagoras-0.24.4 → pythagoras-0.24.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pythagoras
-Version: 0.24.4
+Version: 0.24.6
 Summary: Planet-scale distributed computing in Python.
 Keywords: cloud,ML,AI,serverless,distributed,parallel,machine-learning,deep-learning,pythagoras
 Author: Volodymyr (Vlad) Pavlov

{pythagoras-0.24.4 → pythagoras-0.24.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pythagoras"
-version = "0.24.4"
+version = "0.24.6"
 authors = [
     {name = "Volodymyr (Vlad) Pavlov", email = "vlpavlov@ieee.org"},
 ]

{pythagoras-0.24.4 → pythagoras-0.24.6}/src/pythagoras/_060_autonomous_code_portals/autonomous_decorators.py

@@ -43,11 +43,16 @@ from persidict import Joker, KEEP_CURRENT
 
 
 class autonomous(safe):
-    """Decorator for enforcing autonomicity requirements for functions.
+    """Decorator that turns a regular function into an autonomous one.
 
-    An autonomous function is only allowed to use the built-in objects
-    (functions, types, variables), as well as global objects,
-    accessible via import statements inside the function body.
+    An autonomous function is a self-contained function: it
+    can only use built-ins and any names it imports inside its own body. This
+    decorator wraps the target callable into an AutonomousFn and enforces both
+    static and runtime autonomy checks via the selected portal.
+
+    Notes:
+        - Only regular (non-async) functions are supported.
+        - Methods, closures, lambdas, and coroutines are not considered autonomous.
     """
     _fixed_args: dict|None
 
@@ -56,6 +61,19 @@ class autonomous(safe):
                  , excessive_logging: bool|Joker = KEEP_CURRENT
                  , portal: AutonomousCodePortal | None = None
                  ):
+        """Initialize the decorator.
+
+        Args:
+            fixed_kwargs: Keyword arguments to pre-bind (partially apply) to the
+                decorated function. These will be merged into every call.
+            excessive_logging: If True, enables verbose logging within the
+                selected portal. KEEP_CURRENT leaves the portal's setting as-is.
+            portal: Portal instance to use for autonomy and safety checks.
+
+        Raises:
+            AssertionError: If portal is not an AutonomousCodePortal or None, or
+                if fixed_kwargs is not a dict or None.
+        """
         assert isinstance(portal, AutonomousCodePortal) or portal is None
         assert isinstance(fixed_kwargs, dict) or fixed_kwargs is None
         safe.__init__(self=self
@@ -65,6 +83,15 @@ class autonomous(safe):
 
 
     def __call__(self, fn: Callable|str) -> AutonomousFn:
+        """Wrap the function with autonomy enforcement.
+
+        Args:
+            fn: The function object to decorate.
+
+        Returns:
+            AutonomousFn: A wrapper that enforces autonomy at decoration and at
+            execution time, with any fixed keyword arguments pre-applied.
+        """
         wrapper = AutonomousFn(fn
             ,portal=self._portal
             ,fixed_kwargs=self._fixed_kwargs

{pythagoras-0.24.4 → pythagoras-0.24.6}/src/pythagoras/_060_autonomous_code_portals/autonomous_portal_core_classes.py

@@ -1,14 +1,7 @@
 from __future__ import annotations
 
 import builtins
-from typing import Callable, Any
-
-from persidict import PersiDict, Joker, KEEP_CURRENT
-
-from .._010_basic_portals import PortalAwareClass
-from .._010_basic_portals.basic_portal_core_classes import _visit_portal
 from .._020_ordinary_code_portals.code_normalizer import _pythagoras_decorator_names
-from .._030_data_portals import DataPortal
 from .._040_logging_code_portals import KwArgs
 
 from .._060_autonomous_code_portals.names_usage_analyzer import (
@@ -17,12 +10,27 @@ from .._060_autonomous_code_portals.names_usage_analyzer import (
 from .._050_safe_code_portals.safe_portal_core_classes import *
 
 class AutonomousCodePortal(SafeCodePortal):
-    
+    """Portal configured for enforcing autonomy constraints.
+
+    This portal behaves like SafeCodePortal but is specialized for autonomous
+    functions. It controls logging and consistency checks for operations related
+    to AutonomousFn instances.
+    """
     def __init__(self
             , root_dict: PersiDict | str | None = None
             , p_consistency_checks: float | Joker = KEEP_CURRENT
             , excessive_logging: bool|Joker = KEEP_CURRENT
             ):
+        """Create an autonomous code portal.
+
+        Args:
+            root_dict: Persistence root backing the portal state. Can be a
+                PersiDict instance, a path string, or None for defaults.
+            p_consistency_checks: Probability [0..1] to run extra consistency
+                checks on operations. KEEP_CURRENT uses the existing setting.
+            excessive_logging: Whether to enable verbose logging. KEEP_CURRENT
+                preserves the existing portal setting.
+        """
         SafeCodePortal.__init__(self
             , root_dict=root_dict
             , p_consistency_checks=p_consistency_checks
@@ -30,10 +38,19 @@ class AutonomousCodePortal(SafeCodePortal):
 
 
 class AutonomousFnCallSignature(SafeFnCallSignature):
-    """A signature of a call to an autonomous function"""
+    """A signature of a call to an autonomous function.
+
+    This extends SafeFnCallSignature to reference AutonomousFn instances.
+    """
     _fn_cache: AutonomousFn | None
 
     def __init__(self, fn: AutonomousFn, arguments: dict):
+        """Create a call signature for an autonomous function.
+
+        Args:
+            fn: The autonomous function being called.
+            arguments: The call-time arguments mapping (already validated).
+        """
         assert isinstance(fn, AutonomousFn)
         assert isinstance(arguments, dict)
         super().__init__(fn, arguments)
@@ -45,7 +62,13 @@ class AutonomousFnCallSignature(SafeFnCallSignature):
 
 
 class AutonomousFn(SafeFn):
+    """A SafeFn wrapper that enforces function autonomy rules.
 
+    AutonomousFn performs static validation at construction time to ensure that
+    the wrapped function uses only built-ins or names imported inside its body,
+    has no yield statements, and does not reference nonlocal variables.
+    It also supports partial application via fixed keyword arguments.
+    """
     _fixed_kwargs_cache: KwArgs | None
     _fixed_kwargs_packed: KwArgs | None
 
@@ -53,6 +76,20 @@ class AutonomousFn(SafeFn):
                  , fixed_kwargs: dict[str,Any]|None = None
                  , excessive_logging: bool|Joker = KEEP_CURRENT
                  , portal: AutonomousCodePortal|None = None):
+        """Construct an AutonomousFn and validate autonomy constraints.
+
+        Args:
+            fn: The function object, a string with the function's source code,
+                or an existing SafeFn to wrap. If an AutonomousFn is provided,
+                fixed_kwargs are merged.
+            fixed_kwargs: Keyword arguments to pre-bind (partially apply).
+            excessive_logging: Verbose logging flag or KEEP_CURRENT.
+            portal: AutonomousCodePortal to use; may be None to defer.
+
+        Raises:
+            AssertionError: If static analysis detects violations of autonomy
+                (nonlocal/global unbound names, missing imports, or yield usage).
+        """
         super().__init__(fn=fn
             , portal = portal
             , excessive_logging = excessive_logging)
@@ -105,6 +142,11 @@ class AutonomousFn(SafeFn):
 
     @property
     def fixed_kwargs(self) -> KwArgs:
+        """KwArgs of pre-bound keyword arguments for this function.
+
+        Returns:
+            KwArgs: The fixed keyword arguments.
+        """
         if not hasattr(self, "_fixed_kwargs_cache"):
             with self.portal:
                 self._fixed_kwargs_cache = self._fixed_kwargs_packed.unpack()
@@ -112,6 +154,19 @@ class AutonomousFn(SafeFn):
 
 
     def execute(self, **kwargs) -> Any:
+        """Execute the function within the portal, applying fixed kwargs.
+
+        Any kwargs provided here must not overlap with pre-bound fixed kwargs.
+
+        Args:
+            **kwargs: Call-time keyword arguments.
+
+        Returns:
+            Any: Result of the wrapped function call.
+
+        Raises:
+            AssertionError: If provided kwargs overlap with fixed kwargs.
+        """
         with self.portal:
             overlapping_keys = set(kwargs.keys()) & set(self.fixed_kwargs.keys())
             assert len(overlapping_keys) == 0
@@ -120,16 +175,33 @@ class AutonomousFn(SafeFn):
 
 
     def get_signature(self, arguments:dict) -> AutonomousFnCallSignature:
+        """Build a call signature object for this function.
+
+        Args:
+            arguments: Mapping of argument names to values for this call.
+
+        Returns:
+            AutonomousFnCallSignature: The signature representing this call.
+        """
         return AutonomousFnCallSignature(fn=self, arguments=arguments)
 
 
     def fix_kwargs(self, **kwargs) -> AutonomousFn:
-        """Create a new function by pre-filling some arguments.
+        """Create a new autonomous function with some kwargs pre-filled.
 
-        This is called a partial application in functional programming
-        It allows creating specialized functions from general ones by
-        transforming a function with multiple parameters
-        into another function with fewer parameters by fixing some arguments.
+        This is partial application: it creates a function with fewer parameters
+        by fixing a subset of keyword arguments.
+
+        Args:
+            **kwargs: Keyword arguments to fix for the new function.
+
+        Returns:
+            AutonomousFn: A new wrapper that will always apply the provided
+            keyword arguments in addition to already fixed ones.
+
+        Raises:
+            AssertionError: If any of the provided kwargs overlap with already
+                fixed kwargs.
         """
 
         overlapping_keys = set(kwargs.keys()) & set(self.fixed_kwargs.keys())
@@ -140,6 +212,13 @@ class AutonomousFn(SafeFn):
 
 
     def _first_visit_to_portal(self, portal: DataPortal) -> None:
+        """Hook called on the first visit to a data portal.
+
+        Ensures that fixed kwargs are materialized (packed) within the portal.
+
+        Args:
+            portal: The data portal being visited for the first time.
+        """
         super()._first_visit_to_portal(portal)
         with portal:
             _ = self.fixed_kwargs.pack()
@@ -160,6 +239,7 @@ class AutonomousFn(SafeFn):
 
     @property
     def portal(self) -> AutonomousCodePortal:
+        """Return the autonomous portal associated with this function."""
         return super().portal
 
 

{pythagoras-0.24.4 → pythagoras-0.24.6}/src/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-0.24.6/src/pythagoras/_070_protected_code_portals/list_flattener.py

@@ -0,0 +1,50 @@
+from typing import List, Any
+
+
+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 = []
+    stack = [nested_list]
+
+    while stack:
+        current = stack.pop()
+        if isinstance(current, list):
+            stack.extend(reversed(current))
+        else:
+            flattened.append(current)
+
+    return flattened