pythagoras 0.24.3__py3-none-any.whl → 0.24.6__py3-none-any.whl

pythagoras/_040_logging_code_portals/notebook_checker.py

@@ -2,7 +2,15 @@
 _is_in_notebook: bool|None = None
 
 def is_executed_in_notebook() -> bool:
-    """ Return True if running inside a Jupyter notebook. """
+    """Return whether code is running inside a Jupyter/IPython notebook.
+
+    Uses a lightweight heuristic: checks if IPython is present and whether the
+    current shell exposes the set_custom_exc attribute, which is specific to
+    IPython interactive environments (including Jupyter).
+
+    Returns:
+        bool: True if running inside a Jupyter/IPython notebook, False otherwise.
+    """
     global _is_in_notebook
     if _is_in_notebook is not None:
         return _is_in_notebook

pythagoras/_040_logging_code_portals/uncaught_exceptions.py

@@ -16,6 +16,17 @@ from .._800_signatures_and_converters.random_signatures import (
 
 
 def pth_excepthook(exc_type, exc_value, trace_back) -> None:
+    """sys.excepthook replacement that logs uncaught exceptions.
+
+    Args:
+        exc_type: The exception class.
+        exc_value: The exception instance.
+        trace_back: Traceback object for the exception.
+
+    Side Effects:
+        - Records the exception in the active LoggingCodePortal's crash history.
+        - Calls the original sys.__excepthook__ after logging.
+    """
     if _exception_needs_to_be_processed(exc_type, exc_value, trace_back):
         exception_id = "app_"+ get_random_signature() + "_crash"
         event_body = add_execution_environment_summary(
@@ -30,6 +41,17 @@ def pth_excepthook(exc_type, exc_value, trace_back) -> None:
 
 def pth_excepthandler(_, exc_type, exc_value
                     , trace_back, tb_offset=None) -> None:
+    """IPython custom exception handler that logs uncaught exceptions.
+
+    This signature matches IPython's set_custom_exc handler protocol.
+
+    Args:
+        _: Unused first parameter required by IPython.
+        exc_type: The exception class.
+        exc_value: The exception instance.
+        trace_back: Traceback object for the exception.
+        tb_offset: Optional traceback offset used by IPython. Unused.
+    """
     if _exception_needs_to_be_processed(exc_type, exc_value, trace_back):
         exception_id = "app_" + get_random_signature() + "_crash"
         event_body = add_execution_environment_summary(
@@ -45,6 +67,15 @@ _previous_excepthook = None
 _number_of_handlers_registrations = 0
 
 def register_systemwide_uncaught_exception_handlers() -> None:
+    """Install Pythagoras handlers for uncaught exceptions system-wide.
+
+    In standard Python, replaces sys.excepthook; in Jupyter/IPython,
+    registers a custom exception handler via IPython.set_custom_exc when
+    available. Multiple registrations are reference-counted and idempotent.
+
+    Returns:
+        None
+    """
     global _number_of_handlers_registrations, _previous_excepthook
     _number_of_handlers_registrations += 1
     if _number_of_handlers_registrations > 1:
@@ -64,6 +95,15 @@ def register_systemwide_uncaught_exception_handlers() -> None:
 
 
 def unregister_systemwide_uncaught_exception_handlers() -> None:
+    """Uninstall previously registered Pythagoras exception handlers.
+
+    Decrements the registration reference counter. When it reaches zero,
+    restores the previous sys.excepthook (if any) and removes the custom
+    IPython exception handler in notebook environments.
+
+    Returns:
+        None
+    """
     global _number_of_handlers_registrations, _previous_excepthook
     _number_of_handlers_registrations -= 1
     if _number_of_handlers_registrations > 0:

pythagoras/_050_safe_code_portals/safe_decorator.py

@@ -7,12 +7,29 @@ from .safe_portal_core_classes import SafeFn, SafeCodePortal
 
 
 class safe(logging):
-    """A decorator that converts a Python function into a SafeFn object.
+    """Decorator that wraps a callable into a SafeFn for portal execution.
+
+    Usage:
+        @safe()
+        def my_fn(x: int) -> int:
+            return x + 1
+
+    Notes:
+        This decorator configures only logging-related behavior for now. Actual
+        safety/sandboxing is not yet implemented.
     """
 
     def __init__(self
                  , excessive_logging: bool|None|Joker = KEEP_CURRENT
                  , portal: SafeCodePortal | None = None):
+        """Create a safe decorator bound to an optional portal.
+
+        Args:
+            excessive_logging: Whether to enable verbose logging for wrapped
+                calls. KEEP_CURRENT inherits from current context.
+            portal: The SafeCodePortal to attach the resulting SafeFn to. If
+                None, the active portal (if any) may be used by lower layers.
+        """
         assert isinstance(portal, SafeCodePortal) or portal is None
         logging.__init__(self=self
             , portal=portal
@@ -20,6 +37,15 @@ class safe(logging):
 
 
     def __call__(self,fn:Callable)->SafeFn:
+        """Wrap a Python callable into a SafeFn.
+
+        Args:
+            fn: The function to wrap.
+
+        Returns:
+            SafeFn: The wrapped function that can be executed via a portal and
+            will record logging information.
+        """
         wrapper = SafeFn(fn
             , portal=self._portal
             , excessive_logging=self._excessive_logging)

pythagoras/_050_safe_code_portals/safe_portal_core_classes.py

@@ -13,20 +13,43 @@ It will be done soon by integrating https://pypi.org/project/RestrictedPython/
 
 from __future__ import annotations
 
-from typing import Callable
-
-# from parameterizable import register_parameterizable_class
-from persidict import PersiDict, Joker, KEEP_CURRENT
-
 from .._040_logging_code_portals.logging_portal_core_classes import *
 
 
 class SafeCodePortal(LoggingCodePortal):
+    """A portal that executes functions with logging under a "safe" contract.
+
+    Currently, SafeCodePortal inherits all behavior from LoggingCodePortal.
+    True sandboxing/isolation has not yet been implemented and will be
+    introduced in the future (see Notes).
+
+    Notes:
+        The actual safety guarantees (prohibiting access to external
+        filesystem, network, process state, etc.) are not yet enforced.
+        The plan is to integrate RestrictedPython to implement a proper
+        sandbox. Until then, SafeCodePortal behaves like LoggingCodePortal
+        but keeps the API intended for safe execution.
+    """
+
     def __init__(self
                  , root_dict: PersiDict|str|None = None
                  , p_consistency_checks: float|Joker = KEEP_CURRENT
                  , excessive_logging: bool|Joker = KEEP_CURRENT
                  ):
+        """Initialize a SafeCodePortal.
+
+        Args:
+            root_dict: Root persistent dictionary or its path used by the
+                underlying data portal for storing execution artifacts. If a
+                string is provided, it is treated as a path on disk. If None,
+                an in-memory structure may be used (depending on configuration).
+            p_consistency_checks: Probability in [0, 1] of running additional
+                consistency checks on persistent state mutations. Use
+                KEEP_CURRENT to inherit the active setting from parent context.
+            excessive_logging: Whether to enable verbose logging of execution
+                attempts, results, outputs and events. Use KEEP_CURRENT to
+                inherit the active setting from parent context.
+        """
         LoggingCodePortal.__init__(self
             , root_dict=root_dict
             , p_consistency_checks=p_consistency_checks
@@ -34,26 +57,60 @@ class SafeCodePortal(LoggingCodePortal):
 
 
 class SafeFnCallSignature(LoggingFnCallSignature):
-    """A signature of a call to a safe function"""
+    """A signature object describing a call to a SafeFn.
+
+    This specialization only narrows the types returned by some accessors
+    (e.g., fn) to Safe* counterparts. All logging behavior and storage layout
+    are inherited from LoggingFnCallSignature.
+    """
     _fn_cache: SafeFn | None
 
     def __init__(self, fn: SafeFn, arguments: dict):
+        """Construct a signature for a specific SafeFn call.
+
+        Args:
+            fn: The safe function object to be called.
+            arguments: The keyword arguments to use for the call.
+        """
         assert isinstance(fn, SafeFn)
         assert isinstance(arguments, dict)
         super().__init__(fn, arguments)
 
     @property
     def fn(self) -> SafeFn:
-        """Return the function object referenced by the signature."""
+        """Return the SafeFn referenced by this signature.
+
+        Returns:
+            SafeFn: The underlying safe function instance.
+        """
         return super().fn
 
 
 class SafeFn(LoggingFn):
+    """A function wrapper intended for safe execution within a portal.
+
+    SafeFn currently behaves like LoggingFn, adding only type-narrowed
+    accessors for convenience. Future versions will enforce sandboxed
+    execution (see Notes).
+
+    Notes:
+        No actual sandboxing is performed yet. Behavior equals LoggingFn.
+    """
+
     def __init__(self
                  , fn: Callable|str
                  , portal: LoggingCodePortal|None = None
                  , excessive_logging: bool|Joker = KEEP_CURRENT
                  ):
+        """Create a SafeFn wrapper.
+
+        Args:
+            fn: The Python callable to wrap or its import string.
+            portal: The portal to associate with this function. If None, the
+                active portal (if any) may be used by the underlying layers.
+            excessive_logging: Whether to enable verbose logging for this fn.
+                Use KEEP_CURRENT to inherit from the surrounding context.
+        """
         LoggingFn.__init__(self
             , fn = fn
             , portal=portal
@@ -61,23 +118,42 @@ class SafeFn(LoggingFn):
 
 
     def __getstate__(self):
-        """This method is called when the object is pickled."""
+        """Return picklable state.
+
+        Returns:
+            dict: The state returned by the parent LoggingFn for pickling.
+        """
         state = super().__getstate__()
         return state
 
 
     def __setstate__(self, state):
-        """This method is called when the object is unpickled."""
+        """Restore object state after unpickling.
+
+        Args:
+            state: The state previously produced by __getstate__.
+        """
         super().__setstate__(state)
 
 
     @property
     def portal(self) -> SafeCodePortal:
+        """Return the associated SafeCodePortal.
+
+        Returns:
+            SafeCodePortal: The portal that owns this function.
+        """
         return super().portal
 
 
     def get_signature(self, arguments:dict) -> SafeFnCallSignature:
-        return SafeFnCallSignature(fn=self, arguments=arguments)
+        """Create a SafeFnCallSignature for a given call.
 
+        Args:
+            arguments: The keyword arguments for the call.
 
-# register_parameterizable_class(SafeCodePortal)
+        Returns:
+            SafeFnCallSignature: A typed call signature suitable for execution
+            and logging through the portal.
+        """
+        return SafeFnCallSignature(fn=self, arguments=arguments)

pythagoras/_060_autonomous_code_portals/autonomous_decorators.py

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

pythagoras/_060_autonomous_code_portals/autonomous_portal_core_classes.py

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