pythagoras 0.24.3__py3-none-any.whl → 0.24.4__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/_090_swarming_portals/swarming_portals.py

@@ -23,7 +23,7 @@ from parameterizable import (
     access_jsparams)
 from persidict import PersiDict, Joker, KEEP_CURRENT
 
-from parameterizable.json_processor import _Markers
+from parameterizable import *
 
 from .. import VALIDATION_SUCCESSFUL
 from .._010_basic_portals import get_all_known_portals
@@ -212,10 +212,8 @@ class SwarmingPortal(PureCodePortal):
             del self._max_n_workers_cache
         super()._invalidate_cache()
 
-# parameterizable.register_parameterizable_class(SwarmingPortal)
 
-
-def _launch_many_background_workers(portal_init_jsparams:JsonSerializedParams) -> None:
+def _launch_many_background_workers(portal_init_jsparams:JsonSerializedObject) -> None:
     """Launch many background worker processes."""
 
 
@@ -265,7 +263,7 @@ def _launch_many_background_workers(portal_init_jsparams:JsonSerializedParams) -
             list_of_all_workers = new_list_of_all_workers
 
 
-def _background_worker(portal_init_jsparams:JsonSerializedParams) -> None:
+def _background_worker(portal_init_jsparams:JsonSerializedObject) -> None:
     """Background worker that keeps processing random execution requests."""
     portal = parameterizable.loadjs(portal_init_jsparams)
     assert isinstance(portal, SwarmingPortal)
@@ -283,7 +281,7 @@ def _background_worker(portal_init_jsparams:JsonSerializedParams) -> None:
                 portal._randomly_delay_execution()
 
 
-def _process_random_execution_request(portal_init_jsparams:JsonSerializedParams):
+def _process_random_execution_request(portal_init_jsparams:JsonSerializedObject):
     """Process one random execution request."""
     # portal = parameterizable.get_object_from_portable_params(
     #     portal_init_params)

{pythagoras-0.24.3.dist-info → pythagoras-0.24.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pythagoras
-Version: 0.24.3
+Version: 0.24.4
 Summary: Planet-scale distributed computing in Python.
 Keywords: cloud,ML,AI,serverless,distributed,parallel,machine-learning,deep-learning,pythagoras
 Author: Volodymyr (Vlad) Pavlov

{pythagoras-0.24.3.dist-info → pythagoras-0.24.4.dist-info}/RECORD

@@ -6,26 +6,26 @@ pythagoras/_010_basic_portals/long_infoname.py,sha256=KXOmHfQ_5hdZNqfB3Cif2CQiZ3
 pythagoras/_010_basic_portals/portal_tester.py,sha256=x6HiJ3GW9XWplnsT6Ob7QCy2J_JPgGpdaJ8QRyFH-e8,3353
 pythagoras/_010_basic_portals/post_init_metaclass.py,sha256=94FEVMCJBUReRb-fo2-LW8YWXUXw5lLLYlXMnlxHJuU,1495
 pythagoras/_020_ordinary_code_portals/__init__.py,sha256=p3kSqaQYj0xlhk9BwptFgA1USdTbfHkAB5Q9MH-ANI0,1295
-pythagoras/_020_ordinary_code_portals/code_normalizer.py,sha256=7L3P5AaZKS9IPqrIEv5UJc3HHDP48fw6EGQWXZcxQtM,5004
-pythagoras/_020_ordinary_code_portals/function_processing.py,sha256=rlhB0dpaUztv6SM2wlUdaUdETcV2pVUICYufVrQCRcc,3623
-pythagoras/_020_ordinary_code_portals/ordinary_decorator.py,sha256=J4qx03NEEgpYWvg4D8UkAL0PdtAt2sQyMN1op6LMFsA,1028
-pythagoras/_020_ordinary_code_portals/ordinary_portal_core_classes.py,sha256=bY2Hzy19lTezv96dSc1l5SsaGxNkMTOq8IsfnkdV1wY,9743
+pythagoras/_020_ordinary_code_portals/code_normalizer.py,sha256=GJXvBX85W230OcwNAg8XXHAE4m39Q70piJ9g2jcIr4Q,6616
+pythagoras/_020_ordinary_code_portals/function_processing.py,sha256=b9Y4vNf1KSRkpUfS9UmWj3N_CNuPDgUMXdnR3IeyAoM,5021
+pythagoras/_020_ordinary_code_portals/ordinary_decorator.py,sha256=ETmy-HKRzCJfzTPOI-gelQT2tlJpVLRu4I85yv02vuo,1437
+pythagoras/_020_ordinary_code_portals/ordinary_portal_core_classes.py,sha256=C5nobGkYZBi2IHc1Pjfxjx_8h_ajF3Sf9Jq3yxFIR68,15963
 pythagoras/_030_data_portals/__init__.py,sha256=f_F9DCmuVgPMgzwRjuNj6FI63S3oXu7lj3zU66Nw7Hc,1427
-pythagoras/_030_data_portals/data_portal_core_classes.py,sha256=CJmJD2uzZwDuk8lQEJbpWAtN25UF57tkKYTot_yZmfo,20418
-pythagoras/_030_data_portals/ready_and_get.py,sha256=UKiQHkLhdAdvEwP5BTdoAnp4XEs7HDGx6026M2eMuc0,2842
-pythagoras/_030_data_portals/storable_decorator.py,sha256=l8W3GhVmIscgjoCTGq3tmdehKGDLIVnFbTM-GW-1G4g,578
+pythagoras/_030_data_portals/data_portal_core_classes.py,sha256=D_Zg-q15II7IwweEGdBAMhGt09DYN_v_G0XFb5K3WB4,22459
+pythagoras/_030_data_portals/ready_and_get.py,sha256=lgkDygF4lFnZXcCvP5dmvzQX64wrZ8AnYJTI7v2ppng,4172
+pythagoras/_030_data_portals/storable_decorator.py,sha256=u70K8J44NTlofc4HmKHtxxbwKdUkBz6BDsIWds4dALQ,1160
 pythagoras/_040_logging_code_portals/__init__.py,sha256=q2hVyOVgE-9Ru3ycilK98YS9Rat8tSc6erd7AtGxpaA,996
-pythagoras/_040_logging_code_portals/exception_processing_tracking.py,sha256=sU-FCayvppF6gafBRAKsJcMC0JMBcnCCiLzu3yFmxiA,778
-pythagoras/_040_logging_code_portals/execution_environment_summary.py,sha256=hTvTbadYAtisZ4H8rq-n_hsKPCS38jsSz8lw_A1DIqY,2268
-pythagoras/_040_logging_code_portals/kw_args.py,sha256=4EYpPrr2xCgFAarmdFRKlEvGhIHC9kk9kc-VPW4S-XA,2717
-pythagoras/_040_logging_code_portals/logging_decorator.py,sha256=079w2_Z5HhXFLrgyXQekjuOby9CdUgFUGRbRT5lpujU,891
-pythagoras/_040_logging_code_portals/logging_portal_core_classes.py,sha256=FZ_tFg6tVO-kCCXR3X9FLLXxe_5M7tHtkrSmyYhM9f4,21953
-pythagoras/_040_logging_code_portals/notebook_checker.py,sha256=5lQJDIDzhRIRSmX1T88nAREMEMoDDFf0OIKcvTpnhzk,541
+pythagoras/_040_logging_code_portals/exception_processing_tracking.py,sha256=DH1eeJAeVL6Fn-6sXBqx3Ocu2RXxVhLqdH1mvhM24VY,1850
+pythagoras/_040_logging_code_portals/execution_environment_summary.py,sha256=-0ynNibGfRh3J1Sq-N9j7eN1FlGvetEBiW0L4K_qJ30,3813
+pythagoras/_040_logging_code_portals/kw_args.py,sha256=j3Iao80gTBjPx6dk1Azd9D8pcdQ3QdfpkQtQq-4ATV0,4954
+pythagoras/_040_logging_code_portals/logging_decorator.py,sha256=-BGduV2U5SJ40qW8afRCUMrzYv5Pf_CgB4HlSEGDmlA,1766
+pythagoras/_040_logging_code_portals/logging_portal_core_classes.py,sha256=R--DuvPGKzEB4ojWrmmuVU2SezUBVrSXrmdFjnrf72g,34977
+pythagoras/_040_logging_code_portals/notebook_checker.py,sha256=qO7zfMC20hM4tSxlqB7gy6WI4imWX4Xl7ojSwgeVu0A,871
 pythagoras/_040_logging_code_portals/output_capturer.py,sha256=ohCp6qqxL7IuJGfnFuCIgj5Oc4HmC8c7uZGE_uzWkZk,4216
-pythagoras/_040_logging_code_portals/uncaught_exceptions.py,sha256=B3bPvX5nnJJx4JjLSGdl1xXOBU2pqo3CP-MomJAfXaE,3121
+pythagoras/_040_logging_code_portals/uncaught_exceptions.py,sha256=vQrY1mOYdAeKaCmCCY1MUy4xoXurQkfwQuDA43giPl0,4564
 pythagoras/_050_safe_code_portals/__init__.py,sha256=YR-V6W2WZ17SjqmTyY2xdY16xTVEEuLs2MddJj_WCZU,557
-pythagoras/_050_safe_code_portals/safe_decorator.py,sha256=ZTsIMmtb3eGAWSpwdMYXRmIyaJiqV6mdFbB_Mqng784,804
-pythagoras/_050_safe_code_portals/safe_portal_core_classes.py,sha256=G1jYgKaOzkzYxIBMvlLYKMPk2OOpK_SQzMQVsHfBJqY,2562
+pythagoras/_050_safe_code_portals/safe_decorator.py,sha256=AYvX7-km2reRMZ55ndO_2IS2SfHbnpyFv79AVwGg7Po,1681
+pythagoras/_050_safe_code_portals/safe_portal_core_classes.py,sha256=naY4R91N5bcCq8C_-YeBqhrr6UG8zkEQ5t8C3O8ytOw,5673
 pythagoras/_060_autonomous_code_portals/__init__.py,sha256=hnv_dxxRx8c7IDf1QgVYHfYoeVAz8oD9K0oWI_o9N20,1704
 pythagoras/_060_autonomous_code_portals/autonomous_decorators.py,sha256=diWX03jZaInc55jAg391ZRBh-St5exJRLDZiS7dqYvg,2895
 pythagoras/_060_autonomous_code_portals/autonomous_portal_core_classes.py,sha256=21JNwBgEoIHXwCrBPb_eN5vMaHTZ98LdFkHuaMHtkI0,6665
@@ -45,7 +45,7 @@ pythagoras/_080_pure_code_portals/pure_decorator.py,sha256=WHZQzmyxgCpALHrqfeiOM
 pythagoras/_080_pure_code_portals/recursion_pre_validator.py,sha256=n03ooGISJvuwNWteBN9t7CFFSLYAu86AHHFJVcywPqg,1865
 pythagoras/_090_swarming_portals/__init__.py,sha256=TuA17PftTBudptAblNtBlD46BqUiitksOtf3y01QKm0,514
 pythagoras/_090_swarming_portals/output_suppressor.py,sha256=ENRtQtK_-7A94lAqtUQsIWrvtcgKniEpaWcZZZrpfQM,611
-pythagoras/_090_swarming_portals/swarming_portals.py,sha256=ZZuzkAf4Ls9oZyg_yUbj3kEEmXGTPjTCevVh-w7AAkE,12784
+pythagoras/_090_swarming_portals/swarming_portals.py,sha256=3d8sRniGdW_rKp2zKxdqoCvLA4Em1XW5xofhFtzDLf0,12696
 pythagoras/_100_top_level_API/__init__.py,sha256=s5LtwskY2nwkRPFKzP0PrCzQ1c9oScZO0kM9_bWLi3U,64
 pythagoras/_100_top_level_API/default_local_portal.py,sha256=SnykTpTXg1KuT1qwDnrAZ63lYshMy-0nNiUgoOVMxCs,339
 pythagoras/_100_top_level_API/top_level_API.py,sha256=S2NXW4bfL98o6Txn6NM0EeBb1nzwFtPSl-yWNevAQIE,906
@@ -59,6 +59,6 @@ pythagoras/_900_project_stats_collector/__init__.py,sha256=Eagt-BhPPtBGgpMywx2lk
 pythagoras/_900_project_stats_collector/project_analyzer.py,sha256=uhycFKjUIXEpYcZYnak3yn4JFhchl-oZ7wt6spFxhoY,3574
 pythagoras/__init__.py,sha256=TMPtJdSi_WShCpJnsVVdO48Wcvs78GMbUi5gHc1eMLw,1233
 pythagoras/core/__init__.py,sha256=cXtQ-Vbm8TqzazvkFws5cV3AEEYbEKzNXYeuHeLGFK0,328
-pythagoras-0.24.3.dist-info/WHEEL,sha256=X16MKk8bp2DRsAuyteHJ-9qOjzmnY0x1aj0P1ftqqWA,78
-pythagoras-0.24.3.dist-info/METADATA,sha256=tOfVHjizrk-0w3mhvbdhqpSNY-z3U_BhhMuYsa-CCVE,7467
-pythagoras-0.24.3.dist-info/RECORD,,
+pythagoras-0.24.4.dist-info/WHEEL,sha256=X16MKk8bp2DRsAuyteHJ-9qOjzmnY0x1aj0P1ftqqWA,78
+pythagoras-0.24.4.dist-info/METADATA,sha256=o7l1zf9TCe9tz4nhG5KtKVU_z4qI9QQV-h0IHSitI_g,7467
+pythagoras-0.24.4.dist-info/RECORD,,