pythagoras 0.24.2__py3-none-any.whl → 0.24.4__py3-none-any.whl

pythagoras/_010_basic_portals/__init__.py

@@ -32,7 +32,6 @@ be subclassed to provide additional functionality.
 """
 
 from .post_init_metaclass import *
-from .not_picklable_class import *
 from .exceptions import *
 from .basic_portal_core_classes import *
 from .portal_tester import _PortalTester

pythagoras/_010_basic_portals/basic_portal_core_classes.py

@@ -14,12 +14,11 @@ from abc import abstractmethod
 from pathlib import Path
 from typing import TypeVar, Type, Any, NewType
 import pandas as pd
-import parameterizable
+from parameterizable import NotPicklableClass
 from parameterizable import ParameterizableClass, sort_dict_by_keys
 
 from persidict import PersiDict, FileDirDict, SafeStrTuple
 from .post_init_metaclass import PostInitMeta
-from .not_picklable_class import NotPicklable
 from .._800_signatures_and_converters import get_hash_signature
 
 def _describe_persistent_characteristic(name, value) -> pd.DataFrame:
@@ -205,7 +204,7 @@ def get_default_portal_base_dir() -> str:
     return target_directory_str
 
 
-class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
+class BasicPortal(NotPicklableClass,ParameterizableClass, metaclass = PostInitMeta):
     """A base class for portal objects that enable access to 'outside' world.
 
     In a Pythagoras-based application, a portal is the application's 'window'
@@ -359,17 +358,6 @@ class BasicPortal(NotPicklable,ParameterizableClass, metaclass = PostInitMeta):
         return sorted_params
 
 
-    # @property
-    # def auxiliary_param_names(self) -> set[str]:
-    #     """Get the names of the portal's ephemeral parameters.
-    #
-    #     Portal's ephemeral parameters are not stored persistently.
-    #     They affect behaviour of a portal object in an application session,
-    #     but they do not affect behaviour of the actual portal across multiple runs.
-    #     """
-    #     return set()
-
-
     @property
     def _str_id(self) -> PortalStrID:
         """Get the portal's persistent hash.

pythagoras/_020_ordinary_code_portals/code_normalizer.py

@@ -21,16 +21,44 @@ _pythagoras_decorator_names = {
 }
 
 def _get_normalized_function_source_impl(
-        a_func: Callable | str
-        , drop_pth_decorators: bool = False
+        a_func: Callable | str,
+        drop_pth_decorators: bool = False,
         ) -> str:
-        """Return function's source code in a 'canonical' form.
-
-        Remove all comments, docstrings, type annotations, and empty lines;
-        standardize code formatting based on PEP 8.
-        If drop_pth_decorators == True, remove Pythagoras decorators.
-
-        Only regular functions are supported; methods and lambdas are not supported.
+        """Produce a normalized representation of a function's source code.
+
+        The normalization process performs the following steps:
+        1) Accepts either a callable or a string of source code. If a callable
+           is provided, it must be an ordinary function (validated) and its
+           source is retrieved with inspect.getsource.
+        2) Removes empty lines and normalizes indentation for functions defined
+           inside other scopes so that parsing can succeed.
+        3) Parses the code with ast.parse and validates there is exactly one
+           top-level function definition.
+        4) Optionally drops a single Pythagoras decorator (if present) when
+           drop_pth_decorators=True. Only known Pythagoras decorator names are
+           removed; any other decorator remains.
+        5) Strips all docstrings, return/type annotations, and variable
+           annotations from the AST. For nodes that become empty as a result,
+           a "pass" is inserted to keep the code valid.
+        6) Unparses the AST back to code and runs autopep8 to enforce PEP 8
+           formatting.
+
+        Args:
+            a_func: The target function or a string containing its source code.
+            drop_pth_decorators: If True, remove a single known Pythagoras
+                decorator (e.g., @ordinary) from the function, if present.
+
+        Returns:
+            A normalized source code string for the function.
+
+        Raises:
+            NonCompliantFunction: If the function has multiple decorators when
+                a callable or a string representing a single function is
+                expected; or if it fails ordinarity checks.
+            AssertionError: If input is neither a callable nor a string, if
+                parsing assumptions fail (e.g., unexpected AST node types), or
+                when internal integrity checks do not hold.
+            SyntaxError: If the provided source string cannot be parsed.
         """
 
         a_func_name, code = None, ""

pythagoras/_020_ordinary_code_portals/function_processing.py

@@ -6,7 +6,27 @@ from .._010_basic_portals.long_infoname import get_long_infoname
 
 
 def get_function_name_from_source(function_source_code: str) -> str:
-    """Return the name of a function from its source code."""
+    """Extract the function name from a source code snippet.
+
+    This parser scans the source code line-by-line and returns the name
+    from the first line that starts with "def ". It assumes a standard
+    function definition like:
+
+    def my_func(arg1, arg2):
+        ...
+
+    It does not currently detect async functions defined with "async def",
+    and it will raise an error if no valid definition is found.
+
+    Args:
+        function_source_code: The source code containing a function definition.
+
+    Returns:
+        The function name as it appears before the opening parenthesis.
+
+    Raises:
+        ValueError: If no function definition line is found in the input.
+    """
     lines = function_source_code.split('\n')
     for line in lines:
         stripped_line = line.strip()
@@ -18,11 +38,17 @@ def get_function_name_from_source(function_source_code: str) -> str:
 
 
 def accepts_unlimited_positional_args(func: Callable) -> bool:
-    """Check if a function accepts an arbitrary number of positional arguments.
+    """Return True if the function accepts arbitrary positional args.
 
-    This function inspects the signature of the provided callable and
-    checks if it includes a name defined with `*args`,
-    which allows it to accept any number of positional arguments.
+    The check is based on inspect.signature and looks for a parameter of
+    kind VAR_POSITIONAL (i.e., a "*args" parameter).
+
+    Args:
+        func: The callable to inspect.
+
+    Returns:
+        True if the function defines a VAR_POSITIONAL ("*args") parameter;
+        False otherwise.
     """
 
     signature = inspect.signature(func)
@@ -33,7 +59,14 @@ def accepts_unlimited_positional_args(func: Callable) -> bool:
 
 
 def count_parameters_with_defaults(func: Callable) -> int:
-    """Returns the number of function parameters that have default values."""
+    """Count parameters that have default values in the function signature.
+
+    Args:
+        func: The callable to inspect.
+
+    Returns:
+        The number of parameters with default values.
+    """
     signature = inspect.signature(func)
     return sum(
         param.default is not param.empty
@@ -41,18 +74,28 @@ def count_parameters_with_defaults(func: Callable) -> int:
     )
 
 
-def assert_ordinarity(a_func:Callable) -> None:
-    """Assert that a function is ordinary.
+def assert_ordinarity(a_func: Callable) -> None:
+    """Validate that a callable complies with Pythagoras "ordinary" rules.
+
+    In Pythagoras, an "ordinary" function is a regular Python function that:
+    - is a plain function object (not a bound/unbound method, classmethod,
+      staticmethod object, lambda, closure, coroutine, or built-in), and
+    - does not accept unlimited positional arguments (no "*args"), and
+    - has no parameters with default values.
 
-    A function is ordinary if it is not a method,
-    a classmethod, a staticmethod, or a lambda function,
-    or a build-in function.
+    Notes:
+    - Static methods: The handling of static methods is undecided; for now they
+      are treated the same as regular functions only if provided directly as a
+      function object. If a function fails any of the checks below, an error is
+      raised.
 
-    An ordinary function can only be called with keyword arguments,
-    and its parameters can't have default values.
+    Args:
+        a_func: The callable to validate.
 
-    assert_ordinarity checks a function, given as an input name,
-    and throws an exception if the function is not ordinary.
+    Raises:
+        NonCompliantFunction: If the callable violates any of the ordinarity
+            constraints described above (e.g., not a function, is a method,
+            is a lambda/closure/async function, accepts *args, or has defaults).
     """
 
     # TODO: decide how to handle static methods

pythagoras/_020_ordinary_code_portals/ordinary_decorator.py

@@ -14,11 +14,25 @@ class ordinary:
     _portal: OrdinaryCodePortal | None
 
     def __init__(self, portal: OrdinaryCodePortal | None = None):
+       """Initialize the decorator.
+
+       Args:
+           portal: Optional OrdinaryCodePortal to link to the resulting
+               OrdinaryFn wrappers.
+       """
        assert portal is None or isinstance(portal, OrdinaryCodePortal)
        self._portal=portal
 
 
     def __call__(self,fn:Callable)->OrdinaryFn:
+        """Wrap a callable and return its OrdinaryFn representation.
+
+        Args:
+            fn: The function to convert into an OrdinaryFn.
+
+        Returns:
+            OrdinaryFn: The wrapper around the provided function.
+        """
         wrapper = OrdinaryFn(fn, portal=self._portal)
         return wrapper
 

pythagoras/_020_ordinary_code_portals/ordinary_portal_core_classes.py

@@ -15,13 +15,27 @@ from .._010_basic_portals.basic_portal_core_classes import (
 
 
 def get_normalized_function_source(a_func: OrdinaryFn | Callable | str) -> str:
-    """Return a function's source code in a 'canonical' form.
-
-    Remove all comments, docstrings and empty lines;
-    standardize code formatting based on PEP 8.
-
-    Only ordinary functions are supported;
-    methods and lambdas are not supported.
+    """Get the normalized source code for a function or OrdinaryFn.
+
+    This is a convenience wrapper around the internal normalizer that:
+    - Accepts either an OrdinaryFn instance, a regular callable, or a string of
+      source code containing a single function definition.
+    - Returns a normalized string representing the function's source code, with
+      comments, docstrings, type annotations, and empty lines removed and the
+      result formatted per PEP 8.
+
+    Args:
+        a_func: An OrdinaryFn instance, a Python callable, or a string with the
+            function's source code.
+
+    Returns:
+        The normalized source code string.
+
+    Raises:
+        NonCompliantFunction: If the function is not compliant with Pythagoras'
+            ordinarity rules or multiple decorators are present.
+        AssertionError: If input type is invalid or integrity checks fail.
+        SyntaxError: If the provided source cannot be parsed.
     """
 
     if isinstance(a_func, OrdinaryFn):
@@ -34,10 +48,22 @@ def get_normalized_function_source(a_func: OrdinaryFn | Callable | str) -> str:
 REGISTERED_FUNCTIONS_TXT = "Registered functions"
 
 class OrdinaryCodePortal(BasicPortal):
+    """Portal that manages OrdinaryFn instances and their runtime context.
+
+    The portal is responsible for tracking linked OrdinaryFn objects and
+    providing a context manager used during execution. It extends BasicPortal
+    with convenience methods specific to ordinary functions.
+    """
 
     def __init__(self
             , root_dict: PersiDict | str | None = None
             ):
+        """Initialize the portal.
+
+        Args:
+            root_dict: Optional persistence root (PersiDict or path-like string)
+                used by the underlying BasicPortal to store state.
+        """
         super().__init__(root_dict = root_dict)
 
 
@@ -47,7 +73,18 @@ class OrdinaryCodePortal(BasicPortal):
 
 
     def _get_linked_functions_ids(self, target_class: type | None=None) -> set[str]:
-        """Get the set of known functions' IDs"""
+        """Return the set of IDs for functions linked to this portal.
+
+        Args:
+            target_class: Optional subclass of OrdinaryFn to filter the results.
+                If None, OrdinaryFn is used.
+
+        Returns:
+            A set of string IDs corresponding to linked OrdinaryFn instances.
+
+        Raises:
+            TypeError: If target_class is not a subclass of OrdinaryFn.
+        """
         if target_class is None:
             target_class = OrdinaryFn
         if not issubclass(target_class, OrdinaryFn):
@@ -56,7 +93,18 @@ class OrdinaryCodePortal(BasicPortal):
 
 
     def get_linked_functions(self, target_class: type | None=None) -> list[OrdinaryFn]:
-        """Get the list of known functions"""
+        """Return linked OrdinaryFn instances managed by this portal.
+
+        Args:
+            target_class: Optional subclass of OrdinaryFn to filter the results.
+                If None, OrdinaryFn is used.
+
+        Returns:
+            A list of linked OrdinaryFn instances.
+
+        Raises:
+            TypeError: If target_class is not a subclass of OrdinaryFn.
+        """
         if target_class is None:
             target_class = OrdinaryFn
         if not issubclass(target_class, OrdinaryFn):
@@ -65,11 +113,26 @@ class OrdinaryCodePortal(BasicPortal):
 
 
     def get_number_of_linked_functions(self, target_class: type | None=None) -> int:
+        """Return the number of OrdinaryFn objects linked to this portal.
+
+        Args:
+            target_class: Optional subclass of OrdinaryFn to filter the results.
+                If None, OrdinaryFn is used.
+
+        Returns:
+            The number of linked functions matching the filter.
+        """
         return len(self._get_linked_functions_ids(target_class=target_class))
 
 
     def describe(self) -> pd.DataFrame:
-        """Get a DataFrame describing the portal's current state"""
+        """Describe the portal's current state.
+
+        Returns:
+            A pandas DataFrame with runtime characteristics of the portal,
+            including the number of registered functions, combined with the
+            base portal description.
+        """
         all_params = [super().describe()]
 
         all_params.append(_describe_runtime_characteristic(
@@ -110,6 +173,19 @@ class OrdinaryFn(PortalAwareClass):
                  , fn: Callable | str
                  , portal: OrdinaryCodePortal | None = None
                  ):
+        """Create a new OrdinaryFn wrapper.
+
+        Args:
+            fn: Either a regular callable, a string with the function's source,
+                or another OrdinaryFn instance to clone.
+            portal: Optional OrdinaryCodePortal to link to this instance.
+
+        Raises:
+            TypeError: If fn is neither callable, a string, nor an OrdinaryFn.
+            NonCompliantFunction: If the provided function source is not
+                compliant with Pythagoras ordinarity rules.
+            SyntaxError: If the provided source cannot be parsed.
+        """
         PortalAwareClass.__init__(self, portal=portal)
         if isinstance(fn, OrdinaryFn):
             self.__setstate__(deepcopy(fn.__getstate__()))
@@ -125,31 +201,48 @@ class OrdinaryFn(PortalAwareClass):
 
     @property
     def portal(self) -> OrdinaryCodePortal:
-        """Get the portal which the function's methods will be using.
+        """Return the portal used by this function.
+
+        It's either the function's linked portal or, if that is None, the
+        currently active portal from the ambient context.
 
-        It's either the function's linked portal or
-        (if the linked portal is None) the currently active portal.
+        Returns:
+            OrdinaryCodePortal: The portal to be used by this object.
         """
         return super().portal
 
 
     @property
     def source_code(self) -> str:
-        """Get the source code of the function."""
+        """Get the normalized source code of the function.
+
+        Returns:
+            str: The function source after normalization (no comments,
+            docstrings, annotations; PEP 8 formatting).
+        """
         return self._source_code
 
 
     @property
     def name(self) -> str:
-        """Get the name of the function."""
+        """Get the name of the function.
+
+        Returns:
+            str: The function identifier parsed from the source code.
+        """
         if not hasattr(self, "_name_cache") or self._name_cache is None:
             self._name_cache = get_function_name_from_source(self.source_code)
         return self._name_cache
 
 
     @property
-    def hash_signature(self):
-        """Get the hash signature of the function."""
+    def hash_signature(self) -> str:
+        """Get the hash signature of the function.
+
+        Returns:
+            str: A stable, content-derived signature used to uniquely identify
+            the function's normalized source and selected metadata.
+        """
         if not hasattr(self, "_hash_signature_cache"):
             self._hash_signature_cache = get_hash_signature(self)
         return self._hash_signature_cache
@@ -157,6 +250,12 @@ class OrdinaryFn(PortalAwareClass):
 
     @property
     def _virtual_file_name(self):
+        """Return a synthetic filename used when compiling the function.
+
+        Returns:
+            str: A stable file name derived from the function name and hash
+            signature, ending with ".py".
+        """
         if not hasattr(self, "_virtual_file_name_cache") or self._virtual_file_name_cache is None:
             self._virtual_file_name_cache = self.name + "_" + self.hash_signature + ".py"
         return self._virtual_file_name_cache
@@ -164,6 +263,11 @@ class OrdinaryFn(PortalAwareClass):
 
     @property
     def _kwargs_var_name(self):
+        """Return the internal name used to store call kwargs during exec.
+
+        Returns:
+            str: A stable variable name unique to this function instance.
+        """
         if not hasattr(self, "_kwargs_var_name_cache") or self._kwargs_var_name_cache is None:
             self._kwargs_var_name_cache = "kwargs_" + self.name
             self._kwargs_var_name_cache += "_" + self.hash_signature
@@ -172,6 +276,11 @@ class OrdinaryFn(PortalAwareClass):
 
     @property
     def _result_var_name(self):
+        """Return the internal name used to store the call result.
+
+        Returns:
+            str: A stable variable name unique to this function instance.
+        """
         if not hasattr(self, "_result_var_name_cache") or self._result_var_name_cache is None:
             self._result_var_name_cache = "result_" + self.name
             self._result_var_name_cache += "_" + self.hash_signature
@@ -180,6 +289,11 @@ class OrdinaryFn(PortalAwareClass):
 
     @property
     def _tmp_fn_name(self):
+        """Return the internal temporary function name used during exec.
+
+        Returns:
+            str: A stable function name unique to this function instance.
+        """
         if not hasattr(self, "_tmp_fn_name_cache") or self._tmp_fn_name_cache is None:
             self._tmp_fn_name_cache = "func_" + self.name
             self._tmp_fn_name_cache += "_" + self.hash_signature
@@ -188,6 +302,11 @@ class OrdinaryFn(PortalAwareClass):
 
     @property
     def _compiled_code(self):
+        """Return cached code object used to execute the function call.
+
+        Returns:
+            Any: A Python code object suitable for exec.
+        """
         if not hasattr(self, "_compiled_code_cache") or (
                 self._compiled_code_cache is None):
             source_to_execute = self.source_code
@@ -201,11 +320,11 @@ class OrdinaryFn(PortalAwareClass):
 
 
     def _invalidate_cache(self):
-        """Invalidate the function's attribute cache.
+        """Invalidate all cached, derived attributes for this function.
 
-        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.
+        Any property backed by a "_..._cache" attribute is deleted so that it
+        will be recomputed on next access. Also calls the superclass
+        implementation to clear any portal-related caches.
         """
         if hasattr(self, "_compiled_code_cache"):
             del self._compiled_code_cache
@@ -226,10 +345,31 @@ class OrdinaryFn(PortalAwareClass):
 
     @classmethod
     def _compile(cls,*args, **kwargs) -> Any:
+        """Compile Python source code.
+
+        Args:
+            *args: Positional arguments passed to compile().
+            **kwargs: Keyword arguments passed to compile().
+
+        Returns:
+            Any: The code object returned by compile().
+        """
         return compile(*args, **kwargs)
 
 
     def __call__(self,* args, **kwargs) -> Any:
+        """Invoke the wrapped function using only keyword arguments.
+
+        Args:
+            *args: Positional arguments are not allowed and will raise.
+            **kwargs: Keyword arguments to pass to the function.
+
+        Returns:
+            Any: The result of executing the function.
+
+        Raises:
+            AssertionError: If positional arguments are supplied.
+        """
         assert len(args) == 0, (f"Function {self.name} can't"
             + " be called with positional arguments,"
             + " only keyword arguments are allowed.")
@@ -237,7 +377,13 @@ class OrdinaryFn(PortalAwareClass):
 
 
     def _available_names(self):
-        """Returns a dictionary with the names, available inside the function."""
+        """Return names injected into the function's execution context.
+
+        Returns:
+            dict: A mapping of name to object made available during execution,
+            including globals(), the OrdinaryFn itself under its function name
+            and under "self", and the pythagoras package as "pth".
+        """
         import pythagoras as pth
         names= dict(globals())
         names[self.name] = self
@@ -247,6 +393,17 @@ class OrdinaryFn(PortalAwareClass):
 
 
     def execute(self,**kwargs):
+        """Execute the underlying function with the provided keyword args.
+
+        The call is executed inside the portal context, with an execution
+        namespace populated by _available_names().
+
+        Args:
+            **kwargs: Keyword-only arguments for the function call.
+
+        Returns:
+            Any: The value returned by the function.
+        """
         with self.portal:
             names_dict = self._available_names()
             names_dict[self._kwargs_var_name] = kwargs
@@ -256,18 +413,33 @@ class OrdinaryFn(PortalAwareClass):
 
 
     def __getstate__(self):
-        """This method is called when the object is pickled."""
+        """Return the picklable state for this instance.
+
+        Returns:
+            dict: A mapping that contains the normalized source code under the
+            "source_code" key. Runtime caches and portal references are omitted.
+        """
         state = dict(source_code=self._source_code)
         return state
 
 
     def __setstate__(self, state):
-        """This method is called when the object is unpickled."""
+        """Restore instance state from pickled data.
+
+        Args:
+            state (dict): The state mapping previously produced by __getstate__,
+                expected to contain the "source_code" key.
+        """
         super().__setstate__(state)
         self._source_code = state["source_code"]
 
 
     def __hash_signature_descriptor__(self) -> str:
+        """Return a short descriptor string used in hashing.
+
+        Returns:
+            str: Lowercased string combining the function name and class name.
+        """
         descriptor = self.name
         descriptor += "_" + self.__class__.__name__
         descriptor = descriptor.lower()