pythagoras 0.23.17__tar.gz → 0.23.19__tar.gz

{pythagoras-0.23.17 → pythagoras-0.23.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pythagoras
-Version: 0.23.17
+Version: 0.23.19
 Summary: Planet-scale distributed computing in Python.
 Keywords: cloud,ML,AI,serverless,distributed,parallel,machine-learning,deep-learning,pythagoras
 Author: Volodymyr (Vlad) Pavlov
@@ -72,16 +72,16 @@ Pythagoras elevates two popular techniques — memoization and parallelization
 to a global scale and then fuses them, unlocking performance and scalability 
 that were previously out of reach.
 
-* [Pythagoras 101: Introduction to Memoization](https://colab.research.google.com/drive/1bvNXFP1BQJqhoS270Dz1lNT4jPCuj540)
+* [Pythagoras 101: Introduction to Memoization](https://pythagoras.link/tutorial-101)
 
-* [Pythagoras 102: Parallelization Basics](https://colab.research.google.com/drive/1DZxgwoiTnyy1qE7T5JunU4GN4j0w6CVk)
+* [Pythagoras 102: Parallelization Basics](https://pythagoras.link/tutorial-102)
 
 Drawing from many years of functional-programming practice, 
 Pythagoras extends these proven ideas to the next level. 
 In a Pythagoras environment, you can seamlessly employ your 
 preferred functional patterns, augmented by new capabilities.
 
-* [Pythagoras 203: Work with Functions](https://colab.research.google.com/drive/1tlG-p-QnHI6p3K1mdGyHzPzwi6CGRg1a)
+* [Pythagoras 203: Work with Functions](https://pythagoras.link/tutorial-203)
 
 **!!! BOOKMARK THIS PAGE AND COME BACK LATER, WE WILL PUBLISH MORE TUTORIALS SOON !!!**
 
@@ -113,15 +113,13 @@ Decorating a function:
 @pure()
 def my_long_running_function(a:float, b:float) -> float:
   from time import sleep # imports must be placed inside a pure function
-  for i in range(5):
-    sleep(1)
-    print("waiting....")
+  sleep(5)
   return a+10*b
 ```
 
 Using a decorated function synchronously:
 ```python
-result = my_long_running_function(a=1, b=2)
+result = my_long_running_function(a=1, b=2) # only named arguments are allowed
 ```
 
 Using a decorated function asynchronously:
@@ -139,11 +137,7 @@ Pre-conditions for executing a function:
     unused_cpu(cores=10)])
 def my_long_running_function(a:float, b:float) -> float:
   from time import sleep
-  for i in range(5):
-    sleep(1)
-    print(
-        "waiting...."
-        )
+  sleep(5)
   return a+10*b
 ```
 
@@ -154,7 +148,7 @@ def factorial(n:int)->int:
   if n == 1:
     return 1
   else:
-    return n*factorial(n=n-1)
+    return n*factorial(n=n-1) # only named arguments are allowed
 ```
 
 Partial function application:

{pythagoras-0.23.17 → pythagoras-0.23.19}/README.md

@@ -20,16 +20,16 @@ Pythagoras elevates two popular techniques — memoization and parallelization
 to a global scale and then fuses them, unlocking performance and scalability 
 that were previously out of reach.
 
-* [Pythagoras 101: Introduction to Memoization](https://colab.research.google.com/drive/1bvNXFP1BQJqhoS270Dz1lNT4jPCuj540)
+* [Pythagoras 101: Introduction to Memoization](https://pythagoras.link/tutorial-101)
 
-* [Pythagoras 102: Parallelization Basics](https://colab.research.google.com/drive/1DZxgwoiTnyy1qE7T5JunU4GN4j0w6CVk)
+* [Pythagoras 102: Parallelization Basics](https://pythagoras.link/tutorial-102)
 
 Drawing from many years of functional-programming practice, 
 Pythagoras extends these proven ideas to the next level. 
 In a Pythagoras environment, you can seamlessly employ your 
 preferred functional patterns, augmented by new capabilities.
 
-* [Pythagoras 203: Work with Functions](https://colab.research.google.com/drive/1tlG-p-QnHI6p3K1mdGyHzPzwi6CGRg1a)
+* [Pythagoras 203: Work with Functions](https://pythagoras.link/tutorial-203)
 
 **!!! BOOKMARK THIS PAGE AND COME BACK LATER, WE WILL PUBLISH MORE TUTORIALS SOON !!!**
 
@@ -61,15 +61,13 @@ Decorating a function:
 @pure()
 def my_long_running_function(a:float, b:float) -> float:
   from time import sleep # imports must be placed inside a pure function
-  for i in range(5):
-    sleep(1)
-    print("waiting....")
+  sleep(5)
   return a+10*b
 ```
 
 Using a decorated function synchronously:
 ```python
-result = my_long_running_function(a=1, b=2)
+result = my_long_running_function(a=1, b=2) # only named arguments are allowed
 ```
 
 Using a decorated function asynchronously:
@@ -87,11 +85,7 @@ Pre-conditions for executing a function:
     unused_cpu(cores=10)])
 def my_long_running_function(a:float, b:float) -> float:
   from time import sleep
-  for i in range(5):
-    sleep(1)
-    print(
-        "waiting...."
-        )
+  sleep(5)
   return a+10*b
 ```
 
@@ -102,7 +96,7 @@ def factorial(n:int)->int:
   if n == 1:
     return 1
   else:
-    return n*factorial(n=n-1)
+    return n*factorial(n=n-1) # only named arguments are allowed
 ```
 
 Partial function application:

{pythagoras-0.23.17 → pythagoras-0.23.19}/pyproject.toml

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

{pythagoras-0.23.17 → pythagoras-0.23.19}/src/pythagoras/_010_basic_portals/basic_portal_core_classes.py

@@ -1,5 +1,6 @@
-"""This modukle provides foundational functionality for wotk with portals,
-specifically for managing the portal stack and for accessing the current
+"""This module provides foundational functionality for work with portals.
+
+This module specifically handles portal stack management and provides access to the current
 portal. It keeps track of all portals created in the system and manages
 the stack of entered ('active') portals. It also provides a method to
 clear all portals and their state.
@@ -7,7 +8,6 @@ clear all portals and their state.
 
 from __future__ import annotations
 
-import collections
 import random
 import sys
 from abc import abstractmethod
@@ -27,6 +27,14 @@ def _describe_persistent_characteristic(name, value) -> pd.DataFrame:
     A helper function used by the describe() method of BasicPortal
     and its subclasses. It creates a DataFrame with a single row
     containing the type, name, and value of the characteristic.
+
+    Args:
+        name: The name of the characteristic.
+        value: The value of the characteristic.
+
+    Returns:
+        A pandas DataFrame with columns 'type', 'name', and 'value',
+        containing a single row with type="Disk".
     """
     d = dict(
         type="Disk"
@@ -41,6 +49,14 @@ def _describe_runtime_characteristic(name, value) -> pd.DataFrame:
     A helper function used by the describe() method of BasicPortal
     and its subclasses. It creates a DataFrame with a single row
     containing the type, name, and value of the characteristic.
+
+    Args:
+        name: The name of the characteristic.
+        value: The value of the characteristic.
+
+    Returns:
+        A pandas DataFrame with columns 'type', 'name', and 'value',
+        containing a single row with type="Runtime".
     """
     d = dict(
         type = "Runtime"
@@ -54,16 +70,16 @@ BACKEND_TYPE_TXT = "Backend type"
 
 
 def _get_description_value_by_key(dataframe:pd.DataFrame, key:str) -> Any:
-    """
-    Retrieves the value corresponding to a given key from a DataFrame.
+    """Retrieve the value corresponding to a given key from a DataFrame.
 
-    Parameters:
-    - dataframe (pd.DataFrame): The input DataFrame with at least 4 columns.
-    - key (str): The key to search for in the third column of the DataFrame.
+    Args:
+        dataframe: The input DataFrame with 4 columns.
+            It is supposed to be an output of portal.describe() method.
+        key: The key to search for in the third column of the DataFrame.
 
     Returns:
-    - value (any): The value from the fourth column corresponding to the key.
-                   Returns None if the key is not found.
+        The value from the fourth column corresponding to the key.
+        Returns None if the key is not found.
     """
     # Check if the key exists in the 3rd column
     result = dataframe.loc[dataframe.iloc[:, 1] == key]
@@ -80,31 +96,51 @@ _active_portals_counters_stack: list = [int]
 _most_recently_created_portal: BasicPortal | None = None
 
 def get_number_of_known_portals() -> int:
-    """Get the number of portals currently in the system."""
+    """Get the number of portals currently in the system.
+
+    Returns:
+        The total count of all known portals in the system.
+    """
     global _all_known_portals
     return len(_all_known_portals)
 
 
 def get_all_known_portals() -> list[BasicPortal]:
-    """Get a list of all known portals."""
+    """Get a list of all known portals.
+
+    Returns:
+        A list containing all portal instances currently known to the system.
+    """
     global _all_known_portals
     return list(_all_known_portals.values())
 
 
 def get_number_of_portals_in_active_stack() -> int:
-    """Get the number of portals in a stack."""
+    """Get the number of unique portals in the active stack.
+
+    Returns:
+        The count of unique portals currently in the active portal stack.
+    """
     global _active_portals_stack
     return len(set(_active_portals_stack))
 
 
 def get_depth_of_active_portal_stack() -> int:
-    """Get the depth of the active portal stack."""
+    """Get the depth of the active portal stack.
+
+    Returns:
+        The total depth (sum of all counters) of the active portal stack.
+    """
     global _active_portals_counters_stack
     return sum(_active_portals_counters_stack)
 
 
 def get_most_recently_created_portal() -> BasicPortal | None:
-    """Get the most recently created portal, or None if no portals exist."""
+    """Get the most recently created portal.
+
+    Returns:
+        The most recently created portal instance, or None if no portals exist.
+    """
     global _most_recently_created_portal
     return _most_recently_created_portal
 
@@ -117,6 +153,9 @@ def get_active_portal() -> BasicPortal:
     it finds the most recently created portal and makes it active.
     If there are currently no portals exist in the system,
     it creates and returns the default portal.
+
+    Returns:
+        The currently active portal instance.
     """
     global _most_recently_created_portal, _active_portals_stack
 
@@ -132,7 +171,11 @@ def get_active_portal() -> BasicPortal:
 
 
 def get_nonactive_portals() -> list[BasicPortal]:
-    """Get a list of all portals that are not in the active stack."""
+    """Get a list of all portals that are not in the active stack.
+
+    Returns:
+        A list of portal instances that are not currently in the active portal stack.
+    """
     active_portal_str_id = get_active_portal()._str_id
     found_portals = []
     for portal_str_id, portal in _all_known_portals.items():
@@ -149,6 +192,9 @@ def get_default_portal_base_dir() -> str:
     Pythagoras connects to the default local portal
     when no other portal is specified in the
     program which uses Pythagoras.
+
+    Returns:
+        The absolute path to the default portal's base directory as a string.
     """
     home_directory = Path.home()
     target_directory = home_directory / ".pythagoras" / ".default_portal"
@@ -168,7 +214,7 @@ class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
     across multiple runs of the application, and across multiple computers.
 
     A Pythagoras-based application can have multiple portals,
-    and there is usually a current (default) portal, accessible via
+    and there is usually a currently active one, accessible via
     get_active_portal().
 
     BasicPortal is a base class for all portal objects.
@@ -184,6 +230,17 @@ class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
 
 
     def __init__(self, root_dict:PersiDict|str|None = None):
+        """Initialize a BasicPortal instance.
+
+        Sets up the portal with a root dictionary for persistent storage.
+        If no root_dict is provided, uses the default portal base directory
+        to create a FileDirDict.
+
+        Args:
+            root_dict: The root dictionary for persistent storage, a path string,
+                or None to use the default location. If a string is provided,
+                it will be converted to a FileDirDict using that path.
+        """
         ParameterizableClass.__init__(self)
         if root_dict is None:
             root_dict = get_default_portal_base_dir()
@@ -197,7 +254,12 @@ class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
 
 
     def _post_init_hook(self) -> None:
-        """This method is always called after all __init__() methods"""
+        """Execute post-initialization tasks for the portal.
+
+        This method is automatically called after all __init__() methods
+        complete. It registers the portal in the global registry and updates
+        the most recently created portal reference.
+        """
         global _most_recently_created_portal, _all_known_portals
         _all_known_portals[self._str_id] = self
         _most_recently_created_portal = self
@@ -205,7 +267,16 @@ class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
 
     def _get_linked_objects_ids(self
             , target_class: type | None = None) -> set[PObjectStrID]:
-        """Get the set str_ids of objects, linked to the portal."""
+        """Get the set of string IDs of objects linked to this portal.
+
+        Args:
+            target_class: The class type to filter for, or None to include
+                all linked objects regardless of type.
+
+        Returns:
+            A set of string IDs representing objects linked to this portal,
+            optionally filtered by the specified target class.
+        """
         global _all_links_from_objects_to_portals
         result = set()
         for obj_str_id, portal_str_id in _all_links_from_objects_to_portals.items():
@@ -220,7 +291,16 @@ class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
 
 
     def get_linked_objects(self, target_class: type | None = None) -> list[PortalAwareClass]:
-        """Get the list of objects, linked to the portal"""
+        """Get the list of objects linked to this portal.
+
+        Args:
+            target_class: The class type to filter for, or None to include
+                all linked objects regardless of type.
+
+        Returns:
+            A list of PortalAwareClass instances that are linked to this portal,
+            optionally filtered by the specified target class.
+        """
         found_linked_objects_ids = self._get_linked_objects_ids(target_class)
         found_linked_objects = []
         for obj_str_id in found_linked_objects_ids:
@@ -230,12 +310,27 @@ class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
 
 
     def get_number_of_linked_objects(self, target_class: type | None = None) -> int:
-        """Get the number of linked portal-aware objects of the given class name."""
-        return len(self._get_linked_objects_ids())
+        """Get the number of objects linked to this portal.
+
+        Args:
+            target_class: The class type to filter for, or None to include
+                all linked objects regardless of type.
+
+        Returns:
+            The count of portal-aware objects linked to this portal,
+            optionally filtered by the specified target class.
+        """
+        return len(self._get_linked_objects_ids(target_class))
 
 
     @property
     def entropy_infuser(self) -> random.Random:
+        """Get the shared random number generator for the portal system.
+
+        Returns:
+            A Random instance shared across all BasicPortal instances for
+            generating random values and entropy when needed.
+        """
         return BasicPortal._entropy_infuser
 
 
@@ -372,6 +467,16 @@ class PortalAwareClass(metaclass = PostInitMeta):
     _visited_portals: set[str] | None
 
     def __init__(self, portal:BasicPortal|None=None):
+        """Initialize a PortalAwareClass instance.
+
+        Sets up the object with an optional linked portal. If a portal is provided,
+        the object will be linked to that portal and will use it for all operations.
+        If no portal is provided, the object will use the currently active portal.
+
+        Args:
+            portal: The portal to link this object to, or None to use the
+                currently active portal for operations.
+        """
         assert portal is None or isinstance(portal, BasicPortal)
         self._linked_portal_at_init = portal
         # self._hash_id_cache = None
@@ -379,7 +484,12 @@ class PortalAwareClass(metaclass = PostInitMeta):
 
 
     def _post_init_hook(self):
-        """ This method is called after all object's .__init__() methods."""
+        """Execute post-initialization tasks for the portal-aware object.
+
+        This method is automatically called after all object's __init__() methods
+        complete. It registers the object with its linked portal if one was provided
+        during initialization, establishing the connection between the object and portal.
+        """
         global _all_links_from_objects_to_portals
         global _all_activated_portal_aware_objects
         if self._linked_portal_at_init is not None:
@@ -427,6 +537,14 @@ class PortalAwareClass(metaclass = PostInitMeta):
 
 
     def _visit_portal(self, portal: BasicPortal) -> None:
+        """Visit a portal and register the object if this is the first visit.
+
+        Checks if the object has previously visited the specified portal.
+        If this is the first visit, registers the object with that portal.
+
+        Args:
+            portal: The BasicPortal instance to visit.
+        """
         if portal._str_id not in self._visited_portals:
             self._first_visit_to_portal(portal)
 
@@ -463,7 +581,14 @@ class PortalAwareClass(metaclass = PostInitMeta):
 
     @abstractmethod
     def __setstate__(self, state):
-        """This method is called when the object is unpickled."""
+        """This method is called when the object is unpickled.
+
+        Restores the object's state from unpickling and resets portal-related
+        attributes to ensure proper initialization in the new environment.
+
+        Args:
+            state: The state dictionary used for unpickling the object.
+        """
         self._invalidate_cache()
         self._visited_portals = set()
         self._linked_portal_at_init = None

pythagoras-0.23.19/src/pythagoras/_010_basic_portals/exceptions.py

@@ -0,0 +1,36 @@
+class PythagorasException(Exception):
+    """Base exception class for all Pythagoras-related errors.
+
+    This is the base class for all custom exceptions raised by the Pythagoras
+    library. It provides a common interface and functionality for all
+    Pythagoras-specific error conditions.
+
+    Attributes:
+        message: A human-readable description of the error.
+    """
+
+    def __init__(self, message):
+        """Initialize the exception with an error message.
+
+        Args:
+            message: A string describing the error that occurred.
+        """
+        self.message = message
+
+
+class NonCompliantFunction(PythagorasException):
+    """Exception raised when a function does not comply with Pythagoras requirements.
+
+    This exception is raised when a function fails to meet the compliance
+    requirements for use within the Pythagoras framework. This typically
+    occurs when functions cannot be properly serialized, analyzed, or
+    executed within the portal environment.
+    """
+
+    def __init__(self, message):
+        """Initialize the exception with an error message.
+
+        Args:
+            message: A string describing why the function is non-compliant.
+        """
+        PythagorasException.__init__(self, message)

pythagoras-0.23.19/src/pythagoras/_010_basic_portals/long_infoname.py

@@ -0,0 +1,39 @@
+from typing import Any
+
+from persidict import replace_unsafe_chars
+
+
+def get_long_infoname(x: Any, drop_unsafe_chars: bool = True) -> str:
+    """Build a string with extended information about an object and its type.
+
+    Creates a detailed identifier string that includes the module, class name,
+    and object name (if available) of the given object. This is useful for
+    creating unique identifiers for objects in the Pythagoras system.
+
+    Args:
+        x: The object for which to generate the information string.
+        drop_unsafe_chars: If True, replaces unsafe characters with underscores
+            using the persidict.replace_unsafe_chars function. Defaults to True.
+
+    Returns:
+        A string containing extended information about the object, including
+        its module, class name, and object name (when available). Unsafe
+        characters are replaced with underscores if drop_unsafe_chars is True.
+    """
+
+    name = str(type(x).__module__)
+
+    if hasattr(type(x), "__qualname__"):
+        name += "." + str(type(x).__qualname__)
+    else:
+        name += "." + str(type(x).__name__)
+
+    if hasattr(x, "__qualname__"):
+        name += "_" + str(x.__qualname__)
+    elif hasattr(x, "__name__"):
+        name += "_" + str(x.__name__)
+
+    if drop_unsafe_chars:
+        name = replace_unsafe_chars(name, replace_with="_")
+
+    return name

pythagoras-0.23.19/src/pythagoras/_010_basic_portals/not_picklable_class.py

@@ -0,0 +1,36 @@
+class NotPicklable:
+    """A mixin class that prevents objects from being pickled or unpickled.
+
+    This class provides a mechanism to explicitly prevent instances from being
+    serialized using Python's pickle module. Classes that inherit from this
+    mixin will raise TypeError exceptions when pickle attempts to serialize
+    or deserialize them.
+
+    This is useful for objects that contain non-serializable resources or
+    should not be persisted for security or architectural reasons.
+    """
+
+    def __getstate__(self):
+        """Prevent object serialization by raising TypeError.
+
+        This method is called by pickle when attempting to serialize the object.
+        It unconditionally raises a TypeError to prevent pickling.
+
+        Raises:
+            TypeError: Always raised to prevent the object from being pickled.
+        """
+        raise TypeError(f"{type(self).__name__} cannot be pickled")
+
+    def __setstate__(self, state):
+        """Prevent object deserialization by raising TypeError.
+
+        This method is called by pickle when attempting to deserialize the object.
+        It unconditionally raises a TypeError to prevent unpickling.
+
+        Args:
+            state: The state dictionary that would be used for unpickling.
+
+        Raises:
+            TypeError: Always raised to prevent the object from being unpickled.
+        """
+        raise TypeError(f"{type(self).__name__} cannot be unpickled")

pythagoras-0.23.19/src/pythagoras/_010_basic_portals/portal_tester.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+from .basic_portal_core_classes import (
+    BasicPortal, PortalType, _clear_all_portals)
+
+
+class _PortalTester:
+    """A context manager for testing portal objects.
+
+    The class is used to test the portal objects.
+    It ensures that all portal objects are properly initialized and cleared
+    between tests. This class is not supposed to be used in application code,
+    it only exists for unit tests.
+    """
+    _current_instance:_PortalTester|None = None
+    _portal:BasicPortal|None = None
+
+    def __init__(self, portal_class: PortalType | None = None, *args, **kwargs):
+        """Initialize the portal tester.
+
+        Args:
+            portal_class: The portal class to test, or None for no portal.
+                Must be a subclass of BasicPortal if provided.
+            *args: Positional arguments to pass to the portal constructor.
+            **kwargs: Keyword arguments to pass to the portal constructor.
+
+        Raises:
+            Exception: If another _PortalTester instance is already active.
+            AssertionError: If portal_class is not a subclass of BasicPortal.
+        """
+        if _PortalTester._current_instance is not None:
+            raise Exception("_PortalTester can't be nested")
+        _PortalTester._current_instance = self
+
+        if portal_class is not None:
+            assert issubclass(portal_class, BasicPortal)
+        self.portal_class = portal_class
+        self.args = args
+        self.kwargs = kwargs
+
+
+    @property
+    def portal(self) -> BasicPortal | None:
+        """The portal object being tested.
+
+        Returns:
+            The current portal instance if one exists, None otherwise.
+        """
+        return self._portal
+
+    def __enter__(self):
+        """Enter the portal testing context.
+
+        Clears all existing portals and creates a new portal instance if
+        a portal class was specified during initialization. The created
+        portal is automatically entered as a context manager.
+
+        Returns:
+            The _PortalTester instance for use in context management.
+
+        Raises:
+            Exception: If another _PortalTester instance is already active.
+        """
+        if (_PortalTester._current_instance is not None
+                and _PortalTester._current_instance is not self):
+            raise Exception("_PortalTester can't be nested")
+        _PortalTester._current_instance = self
+
+        _clear_all_portals()
+
+        if self.portal_class is not None:
+            self._portal = self.portal_class(*self.args, **self.kwargs)
+            self.portal.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the portal testing context.
+
+        Properly exits the portal context if one was created, clears all
+        portals from the system, and resets the current instance tracker.
+
+        Args:
+            exc_type: Exception type if an exception occurred, None otherwise.
+            exc_val: Exception value if an exception occurred, None otherwise.
+            exc_tb: Exception traceback if an exception occurred, None otherwise.
+        """
+        if self.portal_class is not None:
+            self.portal.__exit__(exc_type, exc_val, exc_tb)
+            self._portal = None
+
+        _clear_all_portals()
+
+        _PortalTester._current_instance = None

pythagoras-0.23.19/src/pythagoras/_010_basic_portals/post_init_metaclass.py

@@ -0,0 +1,34 @@
+from abc import ABCMeta
+
+class PostInitMeta(ABCMeta):
+    """Ensures method ._post_init_hook() is always called after the constructor.
+    
+    This metaclass automatically calls the `_post_init_hook()` method on instances
+    after their construction is complete. This ensures that any post-initialization
+    logic is consistently executed for all instances of classes using this metaclass.
+    """
+    
+    def __call__(self, *args, **kwargs):
+        """Create and initialize an instance, then call its post-init hook.
+
+        This method overrides the default instance creation process to ensure
+        that `_post_init_hook()` is called after the regular constructor.
+        It also includes validation logic for portal-aware objects.
+
+        Args:
+            *args: Positional arguments to pass to the class constructor.
+            **kwargs: Keyword arguments to pass to the class constructor.
+
+        Returns:
+            The fully initialized instance with post-init hook executed.
+
+        Raises:
+            AssertionError: If portal-aware object validation fails.
+        """
+        instance = super().__call__(*args, **kwargs)
+        instance._post_init_hook()
+        #TODO: remove/improve this check at some point in the future
+        if hasattr(instance, '_visited_portals'):
+            assert hasattr(instance, '_linked_portal_at_init')
+            assert len(instance._visited_portals) - int(instance._linked_portal_at_init is not None) == 0
+        return instance

pythagoras-0.23.17/src/pythagoras/_010_basic_portals/exceptions.py

@@ -1,8 +0,0 @@
-class PythagorasException(Exception):
-    def __init__(self, message):
-        self.message = message
-
-
-class NonCompliantFunction(PythagorasException):
-    def __init__(self, message):
-        PythagorasException.__init__(self, message)

pythagoras-0.23.17/src/pythagoras/_010_basic_portals/long_infoname.py

@@ -1,24 +0,0 @@
-from typing import Any
-
-from persidict import replace_unsafe_chars
-
-
-def get_long_infoname(x:Any, drop_unsafe_chars:bool = True) -> str:
-    """Build a string with extended information about an object and its type"""
-
-    name = str(type(x).__module__)
-
-    if hasattr(type(x), "__qualname__"):
-        name += "." + str(type(x).__qualname__)
-    else:
-        name += "." + str(type(x).__name__)
-
-    if hasattr(x, "__qualname__"):
-        name += "_" + str(x.__qualname__)
-    elif hasattr(x, "__name__"):
-        name += "_" + str(x.__name__)
-
-    if drop_unsafe_chars:
-        name = replace_unsafe_chars(name, replace_with="_")
-
-    return name

pythagoras-0.23.17/src/pythagoras/_010_basic_portals/not_picklable_class.py

@@ -1,8 +0,0 @@
-class NotPicklable:
-    def __getstate__(self):
-        """This method is called when the object is pickled."""
-        raise TypeError(f"{type(self).__name__} cannot be pickled")
-
-    def __setstate__(self, state):
-        """This method is called when the object is unpickled."""
-        raise TypeError(f"{type(self).__name__} cannot be unpickled")

pythagoras-0.23.17/src/pythagoras/_010_basic_portals/portal_tester.py

@@ -1,57 +0,0 @@
-from __future__ import annotations
-from .basic_portal_core_classes import (
-    BasicPortal, PortalType, _clear_all_portals)
-
-
-class _PortalTester:
-    """A context manager for testing portal objects.
-
-    The class is used to test the portal objects.
-    It ensures that all portal objects are properly initialized and cleared
-    between tests. This class is not supposed to be used in application code,
-    it only exists for unit tests.
-    """
-    _current_instance:_PortalTester|None = None
-    _portal:BasicPortal|None = None
-
-    def __init__(self,portal_class:PortalType|None = None,*args,**kwargs):
-
-        if _PortalTester._current_instance is not None:
-            raise Exception("_PortalTester can't be nested")
-        _PortalTester._current_instance = self
-
-        if portal_class is not None:
-            assert issubclass(portal_class, BasicPortal)
-        self.portal_class = portal_class
-        self.args = args
-        self.kwargs = kwargs
-
-
-    @property
-    def portal(self) -> BasicPortal|None:
-        """The portal object being tested."""
-        return self._portal
-
-
-    def __enter__(self):
-        if (_PortalTester._current_instance is not None
-                and _PortalTester._current_instance is not self):
-            raise Exception("_PortalTester can't be nested")
-        _PortalTester._current_instance = self
-
-        _clear_all_portals()
-
-        if self.portal_class is not None:
-            self._portal = self.portal_class(*self.args,**self.kwargs)
-            self.portal.__enter__()
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-
-        if self.portal_class is not None:
-            self.portal.__exit__(exc_type, exc_val, exc_tb)
-            self._portal = None
-
-        _clear_all_portals()
-
-        _PortalTester._current_instance = None

pythagoras-0.23.17/src/pythagoras/_010_basic_portals/post_init_metaclass.py

@@ -1,13 +0,0 @@
-from abc import ABCMeta
-
-class PostInitMeta(ABCMeta):
-    """Ensures method ._post_init_hook() is always called after the constructor.
-    """
-    def __call__(self, *args, **kwargs):
-        instance = super().__call__(*args, **kwargs)
-        instance._post_init_hook()
-        #TODO: remove/improve this check at some point in the future
-        if hasattr(instance, '_visited_portals'):
-            assert hasattr(instance, '_linked_portal_at_init')
-            assert len(instance._visited_portals) - int(instance._linked_portal_at_init is not None) == 0
-        return instance