pythagoras 0.22.1__tar.gz → 0.23.0__tar.gz

{pythagoras-0.22.1 → pythagoras-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pythagoras
-Version: 0.22.1
+Version: 0.23.0
 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.22.1 → pythagoras-0.23.0}/pyproject.toml

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

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_010_basic_portals/basic_portal_core_classes.py

@@ -123,7 +123,7 @@ def get_active_portal() -> BasicPortal:
         return _active_portals_stack[-1]
 
     if _most_recently_created_portal is None:
-        sys.modules["pythagoras"].instantiate_default_local_portal()
+        sys.modules["pythagoras"]._instantiate_default_local_portal()
 
     _active_portals_stack.append(_most_recently_created_portal)
     _active_portals_counters_stack.append(1)
@@ -290,9 +290,9 @@ class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
 
 
     def _invalidate_cache(self) -> None:
-        """Invalidate the object's attribute cache.
+        """Invalidate the portal's attribute cache.
 
-        If the object's attribute named ATTR is cached,
+        If the portal's attribute named ATTR is cached,
         its cached value will be stored in an attribute named _ATTR_cache
         This method should delete all such attributes.
         """

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_020_ordinary_code_portals/ordinary_portal_core_classes.py

@@ -15,7 +15,7 @@ from .._010_basic_portals.basic_portal_core_classes import (
 
 
 def get_normalized_function_source(a_func: OrdinaryFn | Callable | str) -> str:
-    """Return function's source code in a 'canonical' form.
+    """Return a function's source code in a 'canonical' form.
 
     Remove all comments, docstrings and empty lines;
     standardize code formatting based on PEP 8.
@@ -201,9 +201,9 @@ class OrdinaryFn(PortalAwareClass):
 
 
     def _invalidate_cache(self):
-        """Invalidate the object's attribute cache.
+        """Invalidate the function's attribute cache.
 
-        If the object's attribute named ATTR is cached,
+        If the function's attribute named ATTR is cached,
         its cached value will be stored in an attribute named _ATTR_cache
         This method should delete all such attributes.
         """
@@ -263,7 +263,7 @@ class OrdinaryFn(PortalAwareClass):
 
     def __setstate__(self, state):
         """This method is called when the object is unpickled."""
-        PortalAwareClass.__setstate__(self, state)
+        super().__setstate__(state)
         self._source_code = state["source_code"]
 
 

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_030_data_portals/__init__.py

@@ -3,7 +3,7 @@
 The most important classes in this sub-package are
 DataPortal and ValueAddr.
 
-A DataPortal is a container for storing and retrieving immutable values.
+A DataPortal is a container for storing and retrieving values.
 In distributed applications, multiple application sessions / processes
 can access the same DataPortal, which enables them to interact
 via passing values through the portal.
@@ -12,18 +12,21 @@ A ValueAddr is a unique identifier for an immutable value.
 Two objects with exactly the same type and value will always have
 exactly the same ValueAddr-es.
 
-A ValueAddr consists of 2 strings: a descriptor, and a hash.
+Conceptually, ValueAddr consists of 2 strings: a descriptor, and a hash signature.
 A descriptor contains human-readable information about an object's type.
 A hash string contains the object's hash signature.
 
+Under the hood, the hash signature is further split into 3 strings:
+a shard, a subshard and a hash tail.
+This is done to address limitations of some file systems
+and to optimize work sith cloud storage (e.g. S3).
+
 Typically, a DataPortal is implemented as
-a shared directory on a file system (e.g. Amazon EFS),
-or as a shared bucket in a cloud storage (e.g. Amazon S3).
-In this case, a ValueAddr becomes a part of file path
-or a URL (e.g. a hash serves as a filename,
+a shared directory on a file system (e.g., Amazon EFS),
+or as a shared bucket in a cloud storage (e.g., Amazon S3).
+In this case, a ValueAddr becomes a part of a file path
+or a URL (e.g., a hash serves as a filename,
 and a prefix is a folder name).
-
-DataPortal is a subclass of OrdinaryCodePortal.
 """
 
 

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_030_data_portals/data_portal_core_classes.py

@@ -8,7 +8,6 @@ from parameterizable import sort_dict_by_keys
 from persidict import PersiDict, SafeStrTuple, replace_unsafe_chars, DELETE_CURRENT
 from persidict import KEEP_CURRENT, Joker
 
-from .._010_basic_portals import BasicPortal
 from .._010_basic_portals import get_active_portal, get_nonactive_portals
 from .._800_signatures_and_converters import get_hash_signature
 
@@ -41,7 +40,7 @@ def get_nonactive_data_portals() -> list[DataPortal]:
 class DataPortal(OrdinaryCodePortal):
     """A portal that persistently stores values.
 
-    Values are accessible via their hash_address-es,
+    Immutable values are accessible via their hash_address-es,
     which are unique identifiers of the values.
 
     If the current portal does not contain a specific value,
@@ -51,8 +50,11 @@ class DataPortal(OrdinaryCodePortal):
 
     A portal can serve as a context manager, enabling the use of the
     'with' statement to support portal-aware code blocks. If some code is
-    supposed to explicitly read anything from a portal, it should be wrapped
-    in a 'with' statement that marks the portal as the current.
+    supposed to explicitly read anything from (or save to) a portal,
+    it should be wrapped in a 'with' statement that
+    marks the portal as active for the duration of the code block.
+
+    DataPortal also supports random consistency checks.
     """
 
     _value_store: WriteOnceDict | None
@@ -190,6 +192,7 @@ class DataPortal(OrdinaryCodePortal):
 
 
 class StorableFn(OrdinaryFn):
+    """An ordinary function that can be persistently stored in a DataPortal."""
 
     _addr_cache: ValueAddr
     _ephemeral_config_params_at_init: dict[str, Any] | None
@@ -219,13 +222,6 @@ class StorableFn(OrdinaryFn):
         return OrdinaryFn.portal.__get__(self)
 
 
-    # @portal.setter
-    # def portal(self, new_portal: DataPortal) -> None:
-    #     if not isinstance(new_portal, DataPortal):
-    #         raise TypeError("portal must be a DataPortal instance")
-    #     OrdinaryFn.portal.__set__(self, new_portal)
-
-
     def _get_config_setting(self, key: SafeStrTuple, portal:DataPortal) -> Any:
         if not isinstance(key, (str,SafeStrTuple)):
             raise TypeError("key must be a SafeStrTuple or a string")
@@ -258,9 +254,9 @@ class StorableFn(OrdinaryFn):
 
 
     def _invalidate_cache(self):
-        """Invalidate the object's attribute cache.
+        """Invalidate the function's attribute cache.
 
-        If the object's attribute named ATTR is cached,
+        If the function's attribute named ATTR is cached,
         its cached value will be stored in an attribute named _ATTR_cache
         This method should delete all such attributes.
         """
@@ -286,11 +282,15 @@ class HashAddr(SafeStrTuple):
     Two objects with exactly the same type and value will always have
     exactly the same HashAddr-es.
 
-    A HashAddr consists of 2 components: a descriptor, and a hash.
-    A descriptor contains human-readable information about an object's type.
-    A hash string contains the object's hash signature. It may contain
-    an optional suffix, which provides additional human-readable
-    information about the object's structure / value.
+    Conceptually, HashAddr consists of 2 components: a descriptor,
+    and a hash signature. A descriptor contains human-readable information
+    about an object's type. A hash signature string contains
+    the object's sha256 value, encoded in base-32.
+
+    Under the hood, the hash signature is further split into 3 strings:
+    a shard, a subshard and a hash tail.
+    This is done to address limitations of some file systems
+    and to optimize work sith cloud storage (e.g. S3).
     """
 
     def __init__(self, descriptor:str
@@ -362,7 +362,7 @@ class HashAddr(SafeStrTuple):
                      , hash_signature:str
                      , assert_readiness:bool=True
                      ) -> HashAddr:
-        """(Re)construct address from text representations of descriptor and hash"""
+        """(Re)construct address from str versions of a descriptor and a hash"""
 
         if not isinstance(descriptor, str) or not isinstance(hash_signature, str):
             raise TypeError("descriptor and hash_signature must be strings")
@@ -382,7 +382,7 @@ class HashAddr(SafeStrTuple):
     @property
     @abstractmethod
     def ready(self) -> bool:
-        """Check if address points to a value that is ready to be retrieved."""
+        """Check if the address points to a value that is ready to be retrieved."""
         # TODO: decide whether we need .ready() at the base class
         raise NotImplementedError
 
@@ -417,12 +417,13 @@ class ValueAddr(HashAddr):
     """A globally unique address of an immutable value.
 
     ValueAddr is a universal global identifier of any (constant) value.
+
     Using only the value's hash should (theoretically) be enough to
-    uniquely address all possible data objects that the humanity  will create
-    in the foreseeable future (see, for example ipfs.io).
+    uniquely address all possible data objects that humanity will create
+    in the foreseeable future (see, for example, ipfs.io).
 
     However, an address also includes a descriptor with an optional suffix.
-    It makes it easier for humans to interpret an address,
+    It makes it easier for humans to interpret an address
     and further decreases collision risk.
     """
     _containing_portals: set[str]
@@ -436,8 +437,8 @@ class ValueAddr(HashAddr):
             descriptor = data_value_addr.descriptor
             hash_signature = data_value_addr.hash_signature
             HashAddr.__init__(self
-                              , descriptor=descriptor
-                              , hash_signature=hash_signature)
+                , descriptor=descriptor
+                , hash_signature=hash_signature)
             return
 
         assert not isinstance(data, HashAddr), (
@@ -447,8 +448,8 @@ class ValueAddr(HashAddr):
         descriptor = self._build_descriptor(data)
         hash_signature = self._build_hash_signature(data)
         HashAddr.__init__(self
-                          , descriptor=descriptor
-                          , hash_signature=hash_signature)
+            , descriptor=descriptor
+            , hash_signature=hash_signature)
 
         self._value_cache = data
 
@@ -583,7 +584,10 @@ class ValueAddr(HashAddr):
                      ) -> HashAddr:
         """(Re)construct address from text representations of descriptor and hash"""
 
-        address = super().from_strings(descriptor=descriptor, hash_signature=hash_signature, assert_readiness=False)
+        address = super().from_strings(
+            descriptor=descriptor
+            , hash_signature=hash_signature
+            , assert_readiness=False)
         address._containing_portals = set()
         if assert_readiness:
             if not address.ready:

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_030_data_portals/ready_and_get.py

@@ -1,6 +1,13 @@
+from typing import Any
+
 from .data_portal_core_classes import HashAddr
 
-def ready(obj, seen=None):
+def ready(obj) -> bool:
+    """Return True if all objects in the data structure are ready."""
+    return _ready(obj)
+
+def _ready(obj, seen=None):
+    """Return True if all objects in the data structure are ready."""
     if seen is None:
         seen = set()
 
@@ -12,14 +19,20 @@ def ready(obj, seen=None):
     if isinstance(obj, HashAddr):
         return obj.ready
     elif isinstance(obj, (list,tuple)):
-        return all(ready(item, seen) for item in obj)
+        return all(_ready(item, seen) for item in obj)
     elif isinstance(obj, dict):
-        return all(ready(value, seen) for key, value in obj.items())
+        return all(_ready(value, seen) for key, value in obj.items())
     else:
         return True
 
 
-def get(obj, seen=None):
+def get(obj:Any) -> Any:
+    """Return copy of data structure with addresses replaced with objects."""
+    return _get(obj)
+
+
+def _get(obj:Any, seen=None)->Any:
+    """Return copy of data structure with addresses replaced with objects."""
     if seen is None:
         seen = dict()
 
@@ -34,12 +47,12 @@ def get(obj, seen=None):
         seen[id(obj)] = placeholder
 
         if isinstance(obj, list):
-            result = [get(item, seen) for item in obj]
+            result = [_get(item, seen) for item in obj]
             # Update the placeholder with the actual values
             placeholder.extend(result)
             return placeholder
         elif isinstance(obj, dict):
-            result = {key: get(value, seen) for key, value in obj.items()}
+            result = {key: _get(value, seen) for key, value in obj.items()}
             # Update the placeholder with the actual values
             placeholder.update(result)
             return placeholder
@@ -47,9 +60,9 @@ def get(obj, seen=None):
     if isinstance(obj, HashAddr):
         result = obj.get()
     elif isinstance(obj, tuple):
-        result = tuple(get(item, seen) for item in obj)
+        result = tuple(_get(item, seen) for item in obj)
     else:
         result = obj
 
     seen[id(obj)] = result
-    return result
+    return result

pythagoras-0.23.0/src/pythagoras/_040_logging_code_portals/__init__.py

@@ -0,0 +1,22 @@
+"""Classes and functions to work with application-level logging.
+
+The main class in this sub-package is LoggingCodePortal, which extends DataPortal
+to provide application-level logging capabilities for events and exceptions.
+'Application-level' means that the events and exceptions are logged into
+location(s) that is(are) the same across the entire application.
+
+LoggingCodePortal provides three attributes, _run_history, _crash_history,
+and  _event_history`, which are persistent dictionaries (PersiDict-s) that store
+the exceptions and logged / recorded events.
+
+Functions log_exception() and `log_event() are provided to log
+exceptions and events. These methods are designed to be
+called from anywhere in the application, and they will log the exception
+or event into the best suitable LoggingPortal.
+"""
+
+from .logging_portal_core_classes import *
+from .kw_args import KwArgs, PackedKwArgs, UnpackedKwArgs
+from .execution_environment_summary import *
+from .logging_decorator import logging
+

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_040_logging_code_portals/exception_processing_tracking.py

@@ -1,22 +1,24 @@
 def _exception_needs_to_be_processed(exc_type, exc_value, trace_back) -> bool:
+    """Chack if the exception needs to be logged by Pythagoras"""
     if exc_type is None:
         return False
 
     if hasattr(exc_value, "__notes__"):
-        if "__suppress_logging__" in exc_value.__notes__:
+        if "__suppress_pythagoras_logging__" in exc_value.__notes__:
             return False
         else:
             return True
 
-    if hasattr(exc_value, "__suppress_logging__"):
+    if hasattr(exc_value, "__suppress_pythagoras_logging__"):
         return False
 
     return True
 
 
 def _mark_exception_as_processed(exc_type, exc_value, trace_back) -> None:
+    """Mark the exception as processed by Pythagoras"""
     if hasattr(exc_value, "add_note"):
         exc_value.add_note(
-            "__suppress_logging__")
+            "__suppress_pythagoras_logging__")
     else:
-        exc_value.__suppress_logging__ = True
+        exc_value.__suppress_pythagoras_logging__ = True

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_040_logging_code_portals/kw_args.py

@@ -7,7 +7,7 @@ from parameterizable import sort_dict_by_keys
 class KwArgs(dict):
     """ A class that encapsulates keyword arguments for a function call.
 
-    It allows to "normalize" the dictionary by sorting the keys
+    It allows "normalizing" the dictionary by sorting the keys
     and replacing values with their hash addresses
     in order to always get the same hash values
     for the same lists of arguments.

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_040_logging_code_portals/logging_portal_core_classes.py

@@ -75,7 +75,6 @@ class LoggingFn(StorableFn):
         return StorableFn.portal.__get__(self)
 
 
-
 class LoggingFnCallSignature:
     """A signature of a call to a (logging) function.
 
@@ -125,9 +124,9 @@ class LoggingFnCallSignature:
 
 
     def _invalidate_cache(self):
-        """Invalidate the object's attribute cache.
+        """Invalidate the function's attribute cache.
 
-        If the object's attribute named ATTR is cached,
+        If the function's attribute named ATTR is cached,
         its cached value will be stored in an attribute named _ATTR_cache
         This method should delete all such attributes.
         """
@@ -389,7 +388,6 @@ class LoggingFnExecutionRecord(NotPicklable):
                 f"{self.call_signature.fn_name} execution results.")
 
 
-
 class LoggingFnExecutionFrame(NotPicklable):
     call_stack: list[LoggingFnExecutionFrame] = []
 
@@ -512,7 +510,7 @@ class LoggingCodePortal(DataPortal):
     from which the event or exception is raised.
 
     The class provides two dictionaries, `_crash_history` and `event_log`,
-    to store the exceptions history and event log respectively.
+    to store the exception history and event log respectively.
 
     Static methods `log_exception` and `log_event` are provided to log
     exceptions and events. These methods are designed to be

pythagoras-0.23.0/src/pythagoras/_050_safe_code_portals/__init__.py

@@ -0,0 +1,15 @@
+"""Classes and functions that allow safe execution of code.
+
+The main classes in this sub-package are SafeCodePortal and SafeFn,
+which extend LoggingCodePortal and LoggingFn
+to provide safe execution capabilities for logging functions.
+
+SafeFn functions can't access (hence can't harm) any data/devices outside
+the function's local scope and the portal.
+
+This functionality has not been implemented yet.
+It will be done soon by integrating https://pypi.org/project/RestrictedPython/
+"""
+
+from .safe_portal_core_classes import *
+from .safe_decorator import *

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_050_safe_code_portals/safe_decorator.py

@@ -7,7 +7,7 @@ from .safe_portal_core_classes import SafeFn, SafeCodePortal
 
 
 class safe(logging):
-    """A decorator that converts a Python function into an SafeFn object.
+    """A decorator that converts a Python function into a SafeFn object.
     """
 
     def __init__(self

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_050_safe_code_portals/safe_portal_core_classes.py

@@ -1,3 +1,16 @@
+"""Classes and functions that allow safe execution of code.
+
+The main classes in this sub-package are SafeCodePortal and SafeFn,
+which extend LoggingCodePortal and LoggingFn
+to provide safe execution capabilities for logging functions.
+
+SafeFn functions can't access (hence can't harm) any data/devices outside
+the function's local scope and the portal.
+
+This functionality has not been implemented yet.
+It will be done soon by integrating https://pypi.org/project/RestrictedPython/
+"""
+
 from __future__ import annotations
 
 from typing import Callable
@@ -49,11 +62,4 @@ class SafeFn(LoggingFn):
         return LoggingFn.portal.__get__(self)
 
 
-    # @portal.setter
-    # def portal(self, new_portal: SafeCodePortal) -> None:
-    #     if not isinstance(new_portal, SafeCodePortal):
-    #         raise TypeError("portal must be a LoggingCodePortal instance")
-    #     LoggingFn.portal.__set__(self, new_portal)
-
-
 register_parameterizable_class(SafeCodePortal)

pythagoras-0.23.0/src/pythagoras/_060_autonomous_code_portals/__init__.py

@@ -0,0 +1,43 @@
+"""Classes and utilities to work with autonomous functions.
+
+In essence, an 'autonomous' function contains self-sufficient code
+that does not depend on external imports or definitions. All required
+imports should be done inside the function body.
+Only ordinary functions can be autonomous.
+
+Autonomous functions are always allowed to use the built-in objects
+(functions, types, variables), as well as global objects,
+explicitly imported inside the function body. An autonomous function
+is allowed to use other autonomous functions if they are passed as
+input arguments to the function.
+
+Autonomous functions are not allowed to:
+
+    * use global objects, imported or defined outside the function body
+      (except built-in objects);
+    * use yield (yield from) statements;
+    * use nonlocal variables, referencing the outside objects.
+
+Autonomous functions can have nested functions and classes.
+
+Only ordinary functions can be autonomous. Asynchronous functions, closures,
+class methods, and lambda functions cannot be autonomous.
+
+Autonomous functions support partial application of arguments:
+the process of pre-filling some arguments of a function,
+producing a new autonomous function that takes the remaining arguments.
+
+This module defines a decorator which is used to
+inform Pythagoras that a function is intended to be autonomous
+and to enforce autonomicity requirements.
+
+Applying a decorator to a function ensures both static and runtime autonomicity
+checks are performed for the function. Static checks happen at the time
+of decoration, while runtime checks happen at the time of function execution.
+"""
+
+
+from .autonomous_portal_core_classes import AutonomousFn, AutonomousCodePortal
+
+from .autonomous_decorators import autonomous
+

pythagoras-0.23.0/src/pythagoras/_060_autonomous_code_portals/autonomous_decorators.py

@@ -0,0 +1,72 @@
+"""Support for work with autonomous functions.
+
+In essence, an 'autonomous' function contains self-sufficient code
+that does not depend on external imports or definitions. All required
+imports should be done inside the function body.
+Only ordinary functions can be autonomous.
+
+Autonomous functions are always allowed to use the built-in objects
+(functions, types, variables), as well as global objects,
+explicitly imported inside the function body. An autonomous function
+is allowed to use other autonomous functions if they are passed as
+input arguments to the function.
+
+Autonomous functions are not allowed to:
+
+    * use global objects, imported or defined outside the function body
+      (except built-in objects);
+    * use yield (yield from) statements;
+    * use nonlocal variables, referencing the outside objects.
+
+Autonomous functions can have nested functions and classes.
+
+Only ordinary functions can be autonomous. Asynchronous functions, closures,
+class methods, and lambda functions cannot be autonomous.
+
+Autonomous functions support partial application of arguments:
+the process of pre-filling some arguments of a function,
+producing a new autonomous function that takes the remaining arguments.
+
+This module defines a decorator which is used to
+inform Pythagoras that a function is intended to be autonomous
+and to enforce autonomicity requirements.
+
+Applying a decorator to a function ensures both static and runtime autonomicity
+checks are performed for the function. Static checks happen at the time
+of decoration, while runtime checks happen at the time of function execution.
+"""
+from typing import Callable
+
+from .._050_safe_code_portals import safe
+from .autonomous_portal_core_classes import AutonomousFn, AutonomousCodePortal
+from persidict import Joker, KEEP_CURRENT
+
+
+class autonomous(safe):
+    """Decorator for enforcing autonomicity requirements for functions.
+
+    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.
+    """
+    _fixed_args: dict|None
+
+    def __init__(self
+                 , fixed_kwargs: dict | None = None
+                 , excessive_logging: bool|Joker = KEEP_CURRENT
+                 , portal: AutonomousCodePortal | None = None
+                 ):
+        assert isinstance(portal, AutonomousCodePortal) or portal is None
+        assert isinstance(fixed_kwargs, dict) or fixed_kwargs is None
+        safe.__init__(self=self
+            , portal=portal
+            , excessive_logging=excessive_logging)
+        self._fixed_kwargs = fixed_kwargs
+
+
+    def __call__(self, fn: Callable|str) -> AutonomousFn:
+        wrapper = AutonomousFn(fn
+            ,portal=self._portal
+            ,fixed_kwargs=self._fixed_kwargs
+            ,excessive_logging=self._excessive_logging)
+        return wrapper

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_060_autonomous_code_portals/autonomous_portal_core_classes.py

@@ -5,7 +5,7 @@ from typing import Callable, Any
 
 from persidict import PersiDict, Joker, KEEP_CURRENT
 from .._020_ordinary_code_portals.code_normalizer import _pythagoras_decorator_names
-from .. import DataPortal
+from .._030_data_portals import DataPortal
 from .._040_logging_code_portals import KwArgs
 
 from .._060_autonomous_code_portals.names_usage_analyzer import (
@@ -14,9 +14,6 @@ from .._060_autonomous_code_portals.names_usage_analyzer import (
 from .._050_safe_code_portals.safe_portal_core_classes import (
     SafeFn, SafeCodePortal)
 
-import pythagoras as pth
-
-
 class AutonomousCodePortal(SafeCodePortal):
     
     def __init__(self
@@ -36,7 +33,7 @@ class AutonomousFn(SafeFn):
     _fixed_kwargs_packed: KwArgs | None
 
     def __init__(self, fn: Callable|str|SafeFn
-                 , fixed_kwargs: dict|None = None
+                 , fixed_kwargs: dict[str,Any]|None = None
                  , excessive_logging: bool|Joker = KEEP_CURRENT
                  , portal: AutonomousCodePortal|None = None):
         super().__init__(fn=fn
@@ -106,6 +103,14 @@ class AutonomousFn(SafeFn):
 
 
     def fix_kwargs(self, **kwargs) -> AutonomousFn:
+        """Create a new function by pre-filling some arguments.
+
+        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.
+        """
+
         overlapping_keys = set(kwargs.keys()) & set(self.fixed_kwargs.keys())
         assert len(overlapping_keys) == 0
         new_fixed_kwargs = {**self.fixed_kwargs,**kwargs}
@@ -139,7 +144,14 @@ class AutonomousFn(SafeFn):
 
 
     def _invalidate_cache(self):
+        """Invalidate the function's attribute cache.
+
+        If the function's attribute named ATTR is cached,
+        its cached value will be stored in an attribute named _ATTR_cache
+        This method should delete all such attributes.
+        """
         super()._invalidate_cache()
         if hasattr(self, "_fixed_kwargs_cached"):
-            assert hasattr(self, "_fixed_kwargs_packed"), "Premature cache invalidation: fixed_kwargs_packed is missing."
+            assert (hasattr(self, "_fixed_kwargs_packed")
+                , "Premature cache invalidation: fixed_kwargs_packed is missing.")
             del self._fixed_kwargs_cached

{pythagoras-0.22.1 → pythagoras-0.23.0}/src/pythagoras/_060_autonomous_code_portals/names_usage_analyzer.py

@@ -14,7 +14,7 @@ class NamesUsedInFunction:
         self.accessible = set() # all names, currently accessable within the function
 
 class NamesUsageAnalyzer(ast.NodeVisitor):
-    """Collect data needed to analyze function autonomy.
+    """Collect data needed to analyze function autonomicity.
 
     This class is a visitor of an AST (Abstract Syntax Tree) that collects data
     needed to analyze function autonomy.