pythagoras 0.22.1__py3-none-any.whl → 0.23.0__py3-none-any.whl

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/_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/_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/_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/_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/_040_logging_code_portals/__init__.py

@@ -1,24 +1,18 @@
 """Classes and functions to work with application-level logging.
 
-The main class in this sub-package is LoggingCodePortal, which extends BasicPortal
+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,
-and does(do) not depend on the specific function from which
-the even or exception is originated.
+location(s) that is(are) the same across the entire application.
 
-BasicPortal provides two attributes, `_crash_history` and `event_log`,
-which are persistent dictionaries (PersiDict-s) that store
-the exceptions history and event log respectively.
+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.
 
-Static methods `log_exception` and `log_event` are provided to log
+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 all the active LoggingPortals. 'Active' LoggingPortals are
-those that have been registered with the current
-stack of nested 'with' statements.
-
-The class also supports logging uncaught exceptions globally.
+or event into the best suitable LoggingPortal.
 """
 
 from .logging_portal_core_classes import *

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/_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/_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/_050_safe_code_portals/__init__.py

@@ -1,2 +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/_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/_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/_060_autonomous_code_portals/__init__.py

@@ -1,46 +1,35 @@
 """Classes and utilities to work with autonomous functions.
 
-In an essence, an 'autonomous' function contains self-sufficient code
+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.
+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,
-created outside the autonomous function,
-if they belong to the same island.
-
-An island is namespace that groups autonomous functions together.
-An autonomous function can use other autonomous functions from the same island
-without explicitly importing them.
+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 and other autonomous functions
-      from the same island);
+      (except built-in objects);
     * use yield (yield from) statements;
     * use nonlocal variables, referencing the outside objects.
 
-If an autonomous function is using other autonomous functions
-from the same island, it is called "loosely autonomous function".
-Otherwise, it is called "strictly autonomous function".
-
 Autonomous functions can have nested functions and classes.
 
-Only regular functions can be autonomous. Asynchronous functions,
-class methods and lambda functions cannot be autonomous.
+Only ordinary functions can be autonomous. Asynchronous functions, closures,
+class methods, and lambda functions cannot be autonomous.
 
-This module defines  decorators which are used to
-inform Pythagoras that a function is intended to be autonomous,
-and to enforce autonomicity requirements:
-@autonomous() and @strictly_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.
 
-It also defines functions which are used to check whether a corresponding
-decorator was added earlier to another function: is_autonomous(),
-is_loosely_autonomous(), and is_strictly_autonomous().
+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

pythagoras/_060_autonomous_code_portals/autonomous_decorators.py

@@ -1,33 +1,39 @@
 """Support for work with autonomous functions.
 
-In essence, an autonomous function contains self-sufficient code
-that does not depend on external imports or definitions.
+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
-may be allowed to use other autonomous functions, which are created or imported
-outside the autonomous function, provided that they belong to the same island.
+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 and, possibly,
-      other autonomous functions from the same island);
+      (except built-in objects);
     * use yield (yield from) statements;
     * use nonlocal variables, referencing the outside objects.
 
-If an autonomous function is allowed to use other autonomous functions,
-it is called "loosely autonomous function". Otherwise, it is called
-"strictly autonomous function".
-
 Autonomous functions can have nested functions and classes.
 
-Only ordinary functions can be autonomous. Asynchronous functions,
-class methods and lambda functions cannot be autonomous.
+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.
 
-Decorators @autonomous, @loosely_autonomous, and @strictly_autonomous
-allow to inform Pythagoras that a function is intended to be autonomous,
-and to enforce autonomicity requirements for the function.
+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
 
@@ -59,31 +65,6 @@ class autonomous(safe):
 
 
     def __call__(self, fn: Callable|str) -> AutonomousFn:
-        """Decorator for autonomous functions.
-
-        It does both static and dynamic checks for autonomous functions.
-
-        Static checks: it checks whether the function uses any global
-        non-built-in objects which do not have associated import statements
-        inside the function. If allow_idempotent==True,
-        global idempotent functions are also allowed.
-        The decorator also checks whether the function is using
-        any non-local objects variables, and whether the function
-        has yield / yield from statements in its code. If static checks fail,
-        the decorator throws a FunctionAutonomicityError exception.
-
-        Dynamic checks: during the execution time it hides all the global
-        and non-local objects from the function, except the built-in ones
-        (and idempotent ones, if allow_idempotent==True).
-        If a function tries to use a non-built-in
-        (and non-idempotent, if allow_idempotent==True)
-        object without explicitly importing it inside the function body,
-        it will result in raising an exception.
-
-        Currently, neither static nor dynamic checks are guaranteed to catch
-        all possible violations of function autonomy requirements.
-        """
-
         wrapper = AutonomousFn(fn
             ,portal=self._portal
             ,fixed_kwargs=self._fixed_kwargs